Writing documentation

To write documentation, we have special symbols for marking the start of documentation comments (doc comments hereafter). Docs are written in a similar fashion, the way we write comments, but they are treated differently compared to ordinary comments and are parsed by rustdoc. The doc comments are divided into two levels and use separate symbols to mark the start of the doc comment:

• Item level: These comments are meant for items within the module such as structs, enum declarations, functions, trait constants, and so on. They should appear above the item. For single-line comments, they start with ///, while multi-line comments begin with /** and end with */.
• Module level: These are comments that appear at the root level, i.e., main.rs, lib.rs, or any other module, and use //! to mark the start of a line comment – or /*! for multi-line comments – before ending them with */. They are suitable for giving a general overview of your crate and example usage.

Within the doc comment, you can write docs using the usual markdown syntax. It also supports writing valid Rust code within backticks (```let a = 23;```), which becomes part of documentation tests.

The preceding notation for writing comments is actually a syntatic sugar for the #[doc="your doc comment"] attribute. These are called doc attributes. When rustdoc parses the /// or /** lines, it converts them into these doc attributes. Alternatively, you can also write docs using these doc attributes.