Let's show an example of documenting code. In the exdoc.rs file, we have documented a function cube as follows:
fn main() {
println!("The cube of 4 is {}", cube(4));
}
/// Calculates the cube `val * val * val`.
///
/// # Examples
///
/// ```
/// let cube = cube(val);
/// ```
pub fn cube(val: u32) -> u32 {
val * val * val
}
If we now invoke rustdoc exdoc.rs on the command line, a doc folder is created. For a project do cargo.doc in the project's root folder. This contains a subfolder exdoc, with an index.html file that is the starting point of a website providing a documentation page for each function. For example, fn.cube.html shows:
Clicking on the exdoc link returns you to the index page.
Documentation comments are written in Markdown (for a brief intro, see https://en.wikipedia.org/wiki/Markdown). They can contain the following special sections preceded by a #. The examples are Panics, Failures, and Safety. Code appears between ```. For a function to be documented, it must belong to the public interface, so it must be prefixed with pub. See Chapter 8, Organizing Code and Macros.
A module can be documented with //! comments that start after the initial {.