How to write comments in Rust: example

In Rust, comments are portions of code are ignored by the compiler but serve as notes for people reading the source code. Programmers use comments to make their code easier to understand.

Line Comments

start with two forward slashes (//) and continue until the end of the line.
For comments multiple lines, need to include // on each line.
Comments can appear on a separate line above the code they explain, which is a common format, or at the end of lines containing code.
It’s fluent in Rust to leave a blank space just after the double slash for improved readability.

Example:

fn main() { 
// fn keyword, function name, empty parentheses for no parameters
   say_hello(); // function body
}
fn say_hello() { // fn keyword, function name, empty parentheses
 println!("Hello, world!"); // function body
}

Block Comments

These are framed within the /* and */ characters.
They can extend over multiple lines.
Nested block comments are supported in Rust.
While supported, some Rust programmers tend to avoid multi-line comments in production code, using them mainly to temporarily exclude code.

Example:

fn main() { 
/* fn keyword, function name, empty parentheses for no parameters,function body,
fn keyword, function name, empty parentheses, function body*/
   say_hello(); 
}
fn say_hello() { 
 println!("Hello, world!"); 
}

Documentation Comments

Rust has a particular kind of comment specifically for documentation, known as documentation comments.
These comments are compiled into an HTML page using the rustdoc tool, which is part of the Rust tool-chain. The generated documentation is typically placed in the target/doc directory.
Documentation comments support You can use Markdown notation to format text. You can use asterisks for italics and bold type, and a blank line creates a paragraph break. Markdown fenced code blocks using triple backticks (“`) or indenting four spaces can be used for larger code samples.

Outer documentation comments:

start with three forward slashes (///) for single-line or /** */ for block comments. They apply to the item immediately following the comment, such as a struct or function.

fn main() { 
/** fn keyword, function name, empty parentheses for no parameters,function body,
fn keyword, function name, empty parentheses, function body*/
   say_hello(); 
}
/// Adds one to the number given.
///
/// # Examples
///
/// ```
/// let five = 5;
///
/// assert_eq!(6, my_crate::add_one(5));
/// ```
fn say_hello() { 
 println!("Hello, world!"); 
}

Inner documentation comments:

start with //! for single-line or /*! */ for block comments. These comments add documentation to the item that contains them, rather than to the item that follows. To document the crate or module as a whole, use this style inside a crate root file (src/lib.rs) or inside a module.

fn main() { 
/*! fn keyword, function name, empty parentheses for no parameters,function body,
fn keyword, function name, empty parentheses, function body*/
   say_hello(); 
}
//! Adds one to the number given.
//!# Adds one to the number given.
fn say_hello() { 
 println!("Hello, world!"); 
}

Documentation comments include specific sections using Markdown headings (#), such as # Examples. Other common sections include Panics (describing scenarios where the function might panic), Errors (for functions returning Result), and Safety (for unsafe functions).

A valuable feature is code examples included in documentation comments can be run as tests using cargo test. This helps ensure that the examples in the documentation remain correct and up-to-date with the code. Running cargo test will execute these “Doc-tests”.

Rust Topics

Page Content

Tutorials