Executable tests in Rustdoc are amazing. For those not involved, they are run when you write `cargo test` and they are included as markdown code blocks in your crate’s documentation.
They’re not an excellent place for extensive testing. But they are super useful for making sure your documentation examples are updated and functional.
#![deny(missing_docs)] is also a great way to ensure you don’t forget to document things.
Doctests are indeed a great format for documentation. They are automatically checked for currentness/correctness, aren't ambiguous like natural language and are close to the implementation.
But I have the feeling that doctests aren't seen as documentation the way that is often desired in the documentation discussions.
They’re not an excellent place for extensive testing. But they are super useful for making sure your documentation examples are updated and functional.
#![deny(missing_docs)] is also a great way to ensure you don’t forget to document things.