3 ms·
One of my favorite features about Rust: this is the default for all documentation comments, and thus for auto-generated API docs.
by pie_flavor 4y ago
One of my favorite features about Rust: this is the default for all documentation comments, and thus for auto-generated API docs.
- boxed 4y agoThis documentation page: https://docs.iommi.rocks/en/latest/forms.html https://docs.iommi.rocks/en/latest/forms.html is generated from this pytest source: https://github.com/TriOptima/iommi/blob/master/docs/test_doc_forms.py https://github.com/TriOptima/iommi/blob/master/docs/test_doc... Is that how rust documentation works?
- pie_flavor 4y agoThe 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. [0]: https://doc.rust-lang.org/stable/src/alloc/string.rs.html#76 https://doc.rust-lang.org/stable/src/alloc/string.rs.html#76 [1]: https://doc.rust-lang.org/stable/std/string/struct.String.html https://doc.rust-lang.org/stable/std/string/struct.String.ht... [2]: https://rust-lang.github.io/mdBook/ https://rust-lang.github.io/mdBook/ [3]: https://doc.rust-lang.org/book/ https://doc.rust-lang.org/book/