<BackDocumenting code in the Rust programming language
8/24/2022Hello 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.
Lates
About graphs, simply.
12/18/2022In 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.
What is the difference between outsourcing development and outstaffing an IT employee for development?
10/17/2022In this article we will understand what outsourcing and outstaff development are.
UI/UX design: The creation process
4/9/2023In this article we will talk about the main steps in the process of creating UI/UX design.
UI/UX design: Introduction
3/29/2023In this article, we begin to get acquainted with UI / UX design. This is the most important stage in the development of any visual application interface.
Meet the Pentest
8/22/2022We are beginning to consider one of the main methods of assessing the security of computer systems and networks for potential vulnerabilities - penetration testing
Reducing the implementation period of MVP
12/8/2022Let's figure out the timing of the implementation of the MVP.
Choosing a programming language
3/17/2023In this article we will talk about choosing a programming language to study
Testing an MVP concept
1/9/2023We will figure out how not to waste the budget on MVP development in vain
Application Architecture Design: Introduction
3/6/2023In this article, we will talk about the process of creating the architecture of an IT solution.
The terms of references: Structure
2/17/2023In this publication we will consider the universal structure of ToR
Incorrect estimation of the cost of IT contractor services
9/10/2022Today 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.
Introduction to Design Patterns in Software Development
10/3/2022In this article, we will begin to dive into the world of optimizing application architecture using design patterns.
Choosing the direction of development for programming training
2/5/2023In this article, you will find out what areas of IT development there are, how they differ and in which they pay more
OSI Model Levels
9/6/2022In this article, we will take a closer look at each of the levels of the OSI model
Main types of application architecture
3/7/2023In this publication, we will look at what application architectures are
10 ways to use Rust Cargo
2/11/2023In this short article I have collected 10 ways to use the build system and package manager of the Rust programming language
Introduction to the OSI model
8/19/2022In this article we begin to consider the fundamental model of network interaction - OSI
CSS animation ripple
8/31/2022A simple example of how to implement ripple animation using HTML and CSS
What is the purpose of an ER-diagram in the development process?
4/28/2023Let's discuss in general terms what an ER diagram is and what it is used for.
From concept to MVP
11/18/2022In 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
What are UML diagrams used for?
5/23/2023In this article we will talk about what UML diagrams are, what they are and where they are used
Introduction to writing the terms of references
1/31/2023The Terms of Reference are an important part of the development process. In this article, we will begin to dive into this issue.
Introduction to software development
10/10/2022Today, 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.
From idea to concept
10/27/2022In this publication, we will talk about how the idea differs from the concept. Let's do this with an example of a specific goal
Weighted graphs
12/26/2022In this article, we will get acquainted with weighted graphs, Dijkstra's algorithm, and its implementation in the Rust programming language.
Why does a VPN business need?
9/27/2022In this article, we will look at how you can secure access to enterprise cloud resources using a VPN