Documenting code in the Rust programming language

Hello everyone 🖖

In this article, I will talk about the main points of documenting code in Rust.

Rust provides the rustdoc tool out of the box. Its main task is to generate documentation for a Rust project. If it's simple, then it takes the corresponding Markdown comments to the code and the code itself and converts them into a beautiful HTML-CSS-JS representation, into a website.

You can call the rustdoc command directly, or using cargo. I prefer the second option.

Go to your working directory, open a terminal window in it and create a new Rust project:

cargo new --lib rust_doc && cd rust_doc

Run the following command in the term:

cargo doc --open

In the browser window that opens, you will see a basic, so far empty, site with documentation for your project. Let's write some code. Open the rust_doc project in your favorite editor, personally I work in Visual Code, and then open the file lib.rs , which is located in the src folder.

Let's create a file first lib.rs the Employee structure and define the basic initialization function new for it, which takes the employee's first name, last name and position at the input, and returns the instance of the Employee structure:

pub struct Employee {
    pub name: String,
    pub lastname: String,
    pub job_title: String,
}

impl Employee {
    pub fn new(name: String, lastname: String, job_title: String) -> Person {
        return Employee {
            name,
            lastname,
            job_title,
        };
    }
}

Now we can start documenting the code.

Add to the very beginning of the file lib.rs the following code snippet, then run cargo doc --open: in the console:

//! # rust_doc lib 
//! *It's created to learn basics 
//! of Rust-code documenting*

Pay attention to the changes that have occurred in the documentation.

Now let's document the Employee structure, after making changes to the code, call the documentation and see what has changed:

/// ## Employee struct
/// It provides information about employee
pub struct Employee {
    /// Name 
    name: String,
    /// Lastanme 
    lastname: String,   
    /// Title 
    job_title: String, 
}

It's time to document the initializer, but with the addition of the cherry on the cake - writing a function test. After changing the code, study the result of calling cargo doc --open.

/// Basic funcs
impl Employee {
    /// Initialize
    /// ```
    /// use rust_doc::Employee;
    /// let emp = Employee::new("Ivan".to_string(),"Yohanson".to_string(),"CEO".to_string());
    /// assert!(emp.name == "Ivan");
    /// assert!(emp.lastname == "Yohanson");
    /// assert!(emp.job_title == "CEO");
    /// ```
    pub fn new(name: String, lastname: String, job_title: String) -> Employee {
        return Employee {
            lastname,
            name,
            job_title,
        };
    }
}

What is in the code, in the comments to the function, is after ``` - this is our test. Let's launch it. Call the following command in the console:

cargo test --doc --package rust_doc -- Employee::new --nocapture

The test was passed successfully.

Please note that when writing the documentation, I used the usual Markdown markup syntax.

You need to document almost everything, so as not to manually search for undocumented lines of code, add the following code to the beginning of the main or lib file, with which you will receive hints if something is not documented:

#![warn(missing_docs)]

Important! If you write a description of the project itself, which is usually located in a lib or main file, then start with the characters //!, if you describe the code directly, then document with ///.

Here is a brief digression into documenting Rust. You can read more about documentation here.

Documenting code in the Rust programming language

Need expert consultation?