Enforcing documentation in a medium-size Rust project
In the last post, I explained what OpenStratos was and how the main logic was being implemented with a finite state machine checked in compilation time.
In a medium-size project like sending balloons to the stratosphere (4k-5k C++ code in the old version), documentation is a must. I’m not the only developer working with the code, and I hope I can get more contributions in the future, so I must document the code-base properly and extensively.
Rust, fortunately, gives us a great documentation system: add some comments using three slashes instead of two at the beginning of each line and run cargo doc --open. All public items will be documented with a lot of information, and the documentation will be opened in your browser (remove the --open flag if you do not want to open the browser). You can even add #![deny(missing_docs)] at the top of your lib.rs or main.rs and the compiler itself will refuse to compile the code if there is any public item without documentation.
This is great if you are creating a library that you only want to upload to crates.io, but it might not be enough if what you want is to have proper documentation for other developers. You will also want to have private items documented, and you will also want to be able to generate HTML documentation for those private members.
Clippy
Here is where clippy has something to say. Clippy is a collection of lints that can be activated on top of those provided by the Rust compiler itself to lint against common spaghetti code or improper API usage. You can find the complete list of lints in its wiki, with a clear description of each of them and an explanation of why should you use them. Clippy turns on some lints by default, and if you follow its guidelines you will create more correct Rust code.
To install clippy you will need Cargo nightly. If you installed Rust with rustup, you can simply install it by running rustup toolchain install nightly. After that, you can install clippy by running cargo +nightly install clippy.
Among clippy’s lints, there is one that is not active by default and that it can make sure we don’t forget our development-oriented private item documentation. Adding #[forbid(missing_docs_in_private_items)] at the top of your lib.rs or main.rs will make the crate to stop compiling (if you compile with cargo clippy instead of cargo build) until you add comments to all private items.
Generating developer documentation
In Rust, if you run cargo doc, you will get the public API documentation for a crate. Once again, if what you want is to have a proper internal documentation, that won’t be enough. There is an open issue to add a command to Cargo to generate documentation to private items, but until then, you will need to run this:
cargo rustdoc --open -- --no-defaults --passes collapse-docs --passes unindent-comments --passes strip-priv-importsNot as easy as it should be, but it works. Once again, you should remove the --open flag if you do not want it to open the browser. You can find the documentation for OpenStratos library here, and here for the launcher.
