Rust for C-Programmers

5.9 Comments in Rust

Comments are an essential part of writing clear, maintainable code. In Rust, comments are ignored by the compiler but are crucial for explaining code logic, intentions, or providing context to future developers (including yourself). Rust supports two types of comments: regular comments and documentation comments.

5.9.1 Regular Comments

Rust uses two types of regular comments:

1. Single-line comments: Single-line comments start with // and continue to the end of the line. These are typically used for short explanations or notes about the code.

   fn main() {
       let number = 5; // This is a single-line comment
       println!("Number is: {}", number); // Prints the value of number
   }

2. Multi-line comments: For longer explanations or temporarily commenting out blocks of code, you can use multi-line comments, which start with /* and end with */.

   fn main() {
       /* 
       This is a multi-line comment.
       It can span multiple lines and is useful
       for providing longer explanations.
       */
       println!("Multi-line comments are useful for long notes.");
   }

   Note: Multi-line comments can be nested, which allows you to comment out sections of code that may already contain comments. This is a useful feature when you want to disable larger portions of code without interfering with existing comments.

   fn main() {
       /*
       This is a multi-line comment.
       /* Nested comments are allowed in Rust. */
       */
   }

5.9.2 Documentation Comments

Rust provides a special type of comment, called documentation comments, to generate API documentation. These comments use /// or //!, depending on their context.

1. Outer documentation comments (///): Outer documentation comments are placed before items like functions, structs, modules, etc. They describe the item they precede and can be processed by Rust’s documentation tool (rustdoc) to generate user-friendly HTML documentation.

   #![allow(unused)]
   fn main() {
   /// Adds two numbers together.
   ///
   /// # Arguments
   ///
   /// * `a` - The first number.
   /// * `b` - The second number.
   ///
   /// # Example
   ///
   /// ```
   /// let result = add(5, 3);
   /// assert_eq!(result, 8);
   /// ```
   fn add(a: i32, b: i32) -> i32 {
       a + b
   }
   }

   The /// comment documents the add function. It includes a description of the function, its arguments, and an example of how to use it. Rustdoc extracts these comments and generates web-based documentation from them.

2. Inner documentation comments (//!): Inner documentation comments are used inside modules or crates to provide information about the enclosing scope. They typically describe the purpose of the module, file, or crate as a whole.

   #![allow(unused)]
   fn main() {
   //! This is a library for basic mathematical operations.
   //! It supports addition, subtraction, multiplication, and division.
   
   /// Multiplies two numbers together.
   fn multiply(a: i32, b: i32) -> i32 {
       a * b
   }
   }

5.9.3 Commenting Guidelines

Here are a few guidelines for using comments effectively in Rust:

• Use single-line comments (//) for short, simple notes.
• Use multi-line comments (/* */) for longer explanations or for temporarily disabling sections of code.
• Avoid excessive comments that simply restate what the code does. Comments should explain why something is done rather than what is being done if the code itself is clear.
• Documentation comments (///, //!) are encouraged for documenting public APIs, especially in libraries, to ensure the code is well-documented and understandable.

5.9.4 Markdown in Documentation Comments

Rust allows you to use Markdown in documentation comments to format text, create lists, and provide code examples. Rustdoc will automatically process the Markdown syntax when generating documentation.

For example, in the following documentation comment, we use Markdown to format the text:

#![allow(unused)]
fn main() {
/// Adds two numbers and returns the result.
///
/// # Example
///
/// ```
/// let result = add(1, 2);
/// assert_eq!(result, 3);
/// ```
///
/// # Panics
///
/// This function will never panic.
fn add(a: i32, b: i32) -> i32 {
    a + b
}
}

Here, the # Example and # Panics headings are created using Markdown, and a code block example is provided inside triple backticks (```).

5.9.5 Summary

• Single-line comments (//) are used for brief remarks.
• Multi-line comments (/* */) are for longer explanations or disabling blocks of code. Rust allows nested comments, which can be useful when temporarily disabling sections of code that already contain comments.
• Documentation comments (///, //!) are used to generate documentation for items such as functions, modules, and structs. They are written in Markdown to create rich, readable documentation.
• It’s a good practice to document public APIs using documentation comments so that users of the code can easily understand its purpose and usage.

Comments are a valuable tool in writing maintainable code. They not only help others understand your code but also serve as helpful reminders for yourself when you revisit the code later.