Rust for C-Programmers

5.10 Comments in Rust

Comments are annotations within the source code ignored by the compiler but essential for human understanding. They should explain the why behind code, document assumptions, or clarify complex sections.

5.10.1 Regular Comments

Used for explanatory notes within function bodies or alongside specific lines of code.

1. Single-line comments: Start with // and extend to the end of the line. Ideal for brief notes.

   // Calculate the average of the two values
   let average = (value1 + value2) / 2.0; // Use floating-point division

2. Multi-line comments (Block comments): Start with /* and end with */. They can span multiple lines and are useful for longer explanations or temporarily disabling blocks of code. Rust supports nested block comments.

   #![allow(unused)]
   fn main() {
   /*
      This function processes user input.
      It first validates the format, then updates the internal state.
      TODO: Add better error handling for malformed input.
      /* Nested comment example: Temporarily disable logging
      println!("Processing input: {}", input);
      */
   */
   fn process_input(input: &str) {
       // ... function body ...
   }
   }

5.10.2 Documentation Comments

Special comments processed by the rustdoc tool to automatically generate HTML documentation for your crate (library or application). They use Markdown syntax internally.

1. Outer doc comments (/// or /** ... */): Document the item that immediately follows them (e.g., a function, struct, enum, trait, module). This is the most common form, used for documenting public APIs.

   #![allow(unused)]
   fn main() {
   /// Represents a geometric point in 2D space.
   pub struct Point {
       /// The x-coordinate value.
       pub x: f64,
       /// The y-coordinate value.
       pub y: f64,
   }
   
   /**
    * Calculates the distance between two points.
    *
    * Uses the Pythagorean theorem.
    *
    * # Arguments
    *
    * * `p1` - The first point.
    * * `p2` - The second point.
    *
    * # Examples
    *
    * ```
    * let point1 = Point { x: 0.0, y: 0.0 };
    * let point2 = Point { x: 3.0, y: 4.0 };
    * assert_eq!(calculate_distance(&point1, &point2), 5.0);
    * ```
    */
   pub fn calculate_distance(p1: &Point, p2: &Point) -> f64 {
       ((p1.x - p2.x).powi(2) + (p1.y - p2.y).powi(2)).sqrt()
   }
   }

2. Inner doc comments (//! or /*! ... */): Document the item that contains them – typically the module or the crate itself. These are usually placed at the very beginning of the file (lib.rs or main.rs for the crate documentation, mod.rs or the module’s file for module documentation).

   #![allow(unused)]
   fn main() {
   // In lib.rs or main.rs
   //! # Geometry Utilities Crate
   //!
   //! This crate provides basic types and functions for working with
   //! 2D geometry, such as points and distance calculations.
   
   // In utils/mod.rs
   /*!
     Internal utility functions module.
     Not part of the public API.
   */
   }

Guidelines:

• Focus comments on explaining intent, assumptions, non-obvious logic, or usage guidelines, rather than simply restating what the code does.
• Keep comments accurate and up-to-date as the code evolves. Stale comments can be worse than no comments.
• Use documentation comments generously for all public API items in libraries. Include examples (``` blocks) to demonstrate usage clearly. This is crucial for making your library usable by others.