Integrated documentation
Writing good documentation for your code is an integral part of software development in my opinion. It clashes a bit with the currently popular stance of good code documenting itself, and while it is true that good code can tell you what is happening, and also many times how it does things, it almost never tells you why it does things in a certain way. Also, I sure do hope those people also mean not documenting functions, constants or modules, because yes, you at least do want documentation for your API.
While many projects still document by writing documentation completely separate from the code it's documenting (or not at all), the current state of the art is putting documentation directly next to the referenced code. The reason is simple: Documentation away from the documented code has almost no chance of a developer looking at it while changing things, therefore being very likely to get outdated very quickly. When you have your documentation next to your code, it usally has some special annotation so some framework can grab and compile it into a more ergonomic representation. This is so that people wanting to read it don't have to dive into the actual code. Rust basically does the same, but with minimal annotation, some extra features and as part of the official Rust toolchain.
Normal comments in Rust are done just like in C, with //
being a one-line comment and /*
introducing a multi-line comment that gets terminated using */
.
If you want to comment the next item below for your documentation, just use ///
or /**
to introduce your comment. The terminator for multi-line comments stays the same.
Multiple documentation comments above the same item will be concatenated and will display as a single one inside your documentation.
Instead of the next item, you can also document the item enclosing your comment.
This is particularly useful with modules, since they usually have their own file and you probably want to have your documentation inside it, instead of it being where the module is linked into your crate.
To do so, use the //!
or /*!
syntax.
No matter which method you use, you should be aware that the text before the first empty line inside a documentation comment is used as the shorthand description you can see in lists and search results. Everything after that empty line is the full text and only visible from the actual page of the item.
Rust documentation comments to have a few tricks up their sleeve. Most importantly, they support markdown syntax
for formatting.
That means you can have headers, subheaders, tables, integrated images (you should host those somewhere else though), hyperlinks and much more.
Also, you can put example code blocks inside them, enabling full syntax highlighting in your documentation.
When the signature of your item references another item, it will automatically contain a link to the latter, even through crate dependencies.
In addition, when linking to items from inside of your comment, you can use the standard Rust path syntax to refer to them.
Finally, since documentation is an integral part of Rust, when uploading your crates to crates.io
, the documentation of each crate will automatically be compiled and uploaded to docs.rs
, with dependencies linked to their own online documentation and with a documentation link added to your uploaded crate.
To finish this chapter, let's have a look how a documented module could look like:
//! An example module.
//!
//! This module dellivers an example of how documentation inside the
//! module code could look like. It contains a [struct](self::MyStruct)
//! and a few functions.
/// An example struct without any fields.
///
/// This struct demonstrates the documentation of a type. It is used
/// as a parameter for [`answer`](self::answer).
pub struct MyStruct;
/// An example function.
pub fn answer(_example: &MyStruct) {}