How it works...

Markdown is a great language that allows for creating formatted documentation quickly. However, feature support is typically tricky, so check out Rust's RFC for supported formatting (https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md) to find out whether some more advanced statements can be used. In general, writing documentation is dreaded by most developers, which is why it's very important to make it as simple and effortless as possible. The /// pattern is quite common and has been expanded in Rust so that the documentation can apply to the code that follows (///) or that contains it (//!). Examples can be seen in step 1 and step 4.

The approach the Rust project chose allows for a few lines explaining the (public) function, and then the rustdoc compiler (invoked in step 2 with cargo doc) does the rest: exposing public members, cross-linking, listing all of the available types and modules, and much more. While the output is fully customizable (step 6), the default is already visually quite appealing (we think). 

Special sections (step 3) add another dimension to the documentation output: they allow for IDEs or editors to make some sense of the provided information and highlight, for example, that (and when) a function may panic. The examples section in your newly generated documentation will even compile and run code in the form of doctests (see the Testing your documentation recipe) so you will be notified when your examples become invalid.

The rustdoc output is also independent of a web server, which means that it can be used wherever static hosting is supported. In fact, the Rust project builds and serves every crate's documentation that is hosted on https://crates.io, on https://docs.rs. 

Now that we can create documentation successfully, we should move on to the next recipe.