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

Hashtags:
#rust
Share:

Lates

About graphs, simply.

In this article, we will begin our acquaintance with graphs, get acquainted with the breadth-first search algorithm (BFS) and implement the graph in the Rust programming language.

#graphs
#rust
#algorithms

What is the difference between outsourcing development and outstaffing an IT employee for development?

In this article we will understand what outsourcing and outstaff development are.

#developmentprocess

Meet the Pentest

We are beginning to consider one of the main methods of assessing the security of computer systems and networks for potential vulnerabilities - penetration testing

#pentest

Reducing the implementation period of MVP

Let's figure out the timing of the implementation of the MVP.

#developmentprocess

Testing an MVP concept

We will figure out how not to waste the budget on MVP development in vain

#developmentprocess

Incorrect estimation of the cost of IT contractor services

Today we will talk about the incorrect assessment of the cost of developing IT solutions. This pain is one of the main ones for enterprises and startups, including IT contractors themselves.

#consultin

Introduction to Design Patterns in Software Development

In this article, we will begin to dive into the world of optimizing application architecture using design patterns.

#designpatterns

OSI Model Levels

In this article, we will take a closer look at each of the levels of the OSI model

#networks
#osi

Introduction to the OSI model

In this article we begin to consider the fundamental model of network interaction - OSI

#networks

CSS animation ripple

A simple example of how to implement ripple animation using HTML and CSS

#css

From concept to MVP

In this article, you will learn, by example, how to move from a concept to an MVP without unnecessary complications in the functionality of the product

#developmentprocess

Introduction to writing the terms of references

The Terms of Reference are an important part of the development process. In this article, we will begin to dive into this issue.

#developmentprocess

Introduction to software development

Today, most companies are faced with IT development and often do not get what they want. In this article, we begin to dive into the process of creating IT solutions.

#developmentprocess

From idea to concept

In this publication, we will talk about how the idea differs from the concept. Let's do this with an example of a specific goal

#developmentprocess

Weighted graphs

In this article, we will get acquainted with weighted graphs, Dijkstra's algorithm, and its implementation in the Rust programming language.

#algorithms
#graphs

Why does a VPN business need?

In this article, we will look at how you can secure access to enterprise cloud resources using a VPN

#networks
#vpn