We have reached stage 6 in iommi: docs from tests.
The docs are written as strings in a special tests directory, with special markup to mark code that is not included in the output, and special code for generating (at test-time) and creating inline iframes for results where applicable.
Code examples in docs that aren't executed will very often be wrong. That's just a fact of life. So we execute them all.
The meaning is the same; the syntax is different. All triple-backtick codeblocks in doc comments, unless annotated 'ignore', are run as tests when you run `cargo test`. So from this file[0], this doc page[1] is generated. And there's more flexibility than 'run or ignore' too, e.g. one on that page is marked ```compile_fail,E0277 to fail the test if it compiles or has a different compilation error than expected. And then every code block known to be runnable has a Run button you can click to open the snippet in the Rust Playground.
These are API docs, but mdBook[2], which generates documentation that looks like this[3], has a test command which checks the code blocks the same way.
The docs are written as strings in a special tests directory, with special markup to mark code that is not included in the output, and special code for generating (at test-time) and creating inline iframes for results where applicable.
Code examples in docs that aren't executed will very often be wrong. That's just a fact of life. So we execute them all.