Generating Documentation in Rust

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 logo

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;
}

src/lib.rs

pub mod cube;

pub mod square;

Now we will create the doc for the following project.

Just run cargo doc in the terminal and boom, your RustDoc is ready at target/doc/calculator/index.html

The generated RustDoc will look like this –

Thanks for reading. See you soon with some amazing Rust Blogs.


knoldus-advt-sticker
Knoldus Pune Careers - Hiring Freshers

Get a head start on your career at Knoldus. Join us!