EPISODE · Oct 3, 2015 · 17 MIN
e001: Document All the Things
from New Rustacean · host Chris Krycho
Document all the things! Subject: Documentation in general, and rustdoc and cargo doc in particular. Follow/Support New Rustacean: Twitter: @newrustacean App.net: @newrustacean Patreon Email: [email protected] Chris Krycho Twitter: @chriskrycho App.net: @chriskrycho Notes This is a mostly-empty module, and it is intended as such. Why? Well, because almost all the sample code exists in these comments, which serve as the show notes. If you listen to the episode or take a look at the source files, you’ll see how it works! The components below are included solely so you can see how the docstrings work with each kind of thing. Make sure to click on the names of the items: there is more documentation there. Again, take a look at the source to see how it looks in the context of a file module. Note that this module-level docstring uses rather than `///`-style comments. This is because this docstring is documenting the item which contains it, rather than the following item. Per [Rust RFC 505][1], the preferred approach is always to use the "following" form (`///`) rather than the "containing" form (), except for module-level docs like these. (I will be following RFC 505 throughout.) Links Rust and MSVC tracking issue Other documentation tools: Predecessors: Python’s Sphinx tool Doxygen JSDoc JavaDoc Other new languages with Markdown tooling Julia has a built-in documentation system Elixir has ex_doc Rust 1.3 release announcement Rust’s package hosting: crates.io Crater for testing for backwards compatibility Semantic versioning “Stability as a Deliverable”: Rust official blog post on version stability, backwards compatibility, and release channels. The Rust book chapter on rustdoc
What this episode covers
Documentation in general, and rustdoc and cargo doc in particular. Document all the things! * Date: October 3, 2015 * Subject: Documentation in general, and rustic and cargo doc in particular. * Audio: * M4A * MP3 Follow/Support * New Rustacean: * Twitter: @newrustacean * App.net: @newrustacean * Patreon * Email: [email protected] * Chris Krycho * Twitter: @chriskrycho * App.net: @chriskrycho Notes This is a mostly-empty module, and it is intended as such. Why? Well, because almost all the sample code exists in these comments, which serve as the show notes. If you listen to the episode or take a look at the source files, you’ll see how it works! The components below are included solely so you can see how the docstrings work with each kind of thing. Make sure to click on the names of the items: there is more documentation there. Again, take a look at the source to see how it looks in the context of a file module. Note that this module-level docstring uses rather than `///`-style comments. This is because this docstring is documenting the item which contains it, rather than the following item. Per [Rust RFC 505][1], the preferred approach is always to use the "following" form (`///`) rather than the "containing" form (), except for module-level docs like these. (I will be following RFC 505 throughout.) Links * Rust and MSVC tracking issue * Other documentation tools: * Predecessors: * Python’s Sphinx tool * Oxygen * JSDoc * JavaDoc * Other new languages with Markdown tooling * Julia has a built-in documentation system * Elixir has ex_doc * Rust 1.3 release announcement * Rust’s package hosting: crates.io * Crater for testing for backwards compatibility * Semantic versioning * “Stability as a Deliverable”: Rust official blog post on version stability, backwards compatibility, and release channels. * The Rust book chapter on rustc
NOW PLAYING
e001: Document All the Things
No transcript for this episode yet
Similar Episodes
Mar 31, 2026 ·54m
Mar 27, 2026 ·14m
Mar 24, 2026 ·42m
Mar 20, 2026 ·42m
Mar 17, 2026 ·41m
Mar 13, 2026 ·44m