Rust Essentials - Second Edition

Documenting a function

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 ...