Generating Documentation in Rust

Reading Time: 2 minutes

If you are coming from Java background, you might not be new to JavaDoc. JavaDoc generates API documentation in HTML format from Java source code.

Rust too supports this type of documentation. This helps us to have the project overview in a HTML format.

So, in this blog I will guide you to create RustDoc for your own project.

We will start with sample code that calculates cube and square of an integer number:

src/main.rs

use calculator::square::calculate_square_of_integer;
use calculator::cube::calculate_cube_of_integer;

/// This application is intended to calculate cube and square of integer values
#[cfg_attr(tarpaulin, skip)]
fn main() {
    let number: u32 = 5;
    println!("Square of {} is {}", number, calculate_square_of_integer(number));
    println!("Cube of {} is {}", number, calculate_cube_of_integer(number));
}

src/square.rs

/// The function calculate_square_of_integer calculates square of the number provided in the argument
/// and return that to the calling function
///
/// # Arguments
///
/// * `operand1` - This is the integer number to calculate the square
///
/// # Return
///
/// This function returns the square of the integer number
pub fn calculate_square_of_integer(operand1: u32) -> u32
{
    let result = operand1 * operand1;
    return result;
}

src/cube.rs

/// The function calculate_cube_of_integer calculates cube of the number provided in the argument
/// and return that to the calling function
///
/// # Arguments
///
/// * `operand1` - This is the integer number to calculate the cube
///
/// # Return
///
/// This function returns the cube of the integer number
pub fn calculate_cube_of_integer(operand1: u32) -> u32
{
    let result: u32 = operand1 * operand1 * operand1;
    return result;
}