Comments

In programming, comments are explanatory notes or annotations embedded within the source code. They are ignored by the compiler or interpreter, meaning they do not affect the program's execution. Their sole purpose is to make the code more understandable for humans—both the original author and other developers who might read or maintain the code later.

Why Use Comments?
* Clarity: Explain complex algorithms, non-obvious logic, or design decisions.
* Intent: Communicate the programmer's intent behind a particular piece of code.
* Readability: Make code easier to follow, especially for large projects or when collaborating.
* Debugging/Temporary Disabling: Temporarily comment out code blocks for testing or to disable features without deleting them.
* Documentation: Generate external documentation from the comments themselves.

Types of Comments in Rust:

1. Line Comments (`//`):
These are the most common type of comments in Rust. Anything from `//` to the end of the line is considered a comment.
```rust
// This is a single-line comment.
let x = 10; // This comments describes the variable x.
```

2. Block Comments (`/* ... */`):
Block comments start with `/*` and end with `*/`. They can span multiple lines and are useful for commenting out larger blocks of code or for multi-line explanations. Rust's block comments can also be nested, which is a rare feature among programming languages.
```rust
/* This is a multi-line
block comment. It can
span as many lines as needed. */

/*
/* Nested block comment example */
*/
```
While available, line comments (`//`) are generally preferred for multi-line explanations in Rust for readability, unless temporarily disabling large code blocks.

3. Documentation Comments (`///` and `//!`):
Rust has special comment types that are used by `rustdoc`, a tool included with Rust, to generate HTML documentation for your library or executable. These comments support Markdown for rich formatting.

* Outer Documentation Comments (`///`):
These comments are typically used to document items (functions, structs, enums, modules, traits, etc.) that *follow* them. They explain the purpose and usage of the item.
```rust
/// Adds two numbers together and returns the result.
///
/// # Arguments
///
/// * `a` - The first number.
/// * `b` - The second number.
///
/// # Examples
///
/// ```
/// let sum = my_crate::add(10, 20);
/// assert_eq!(sum, 30);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
```

* Inner Documentation Comments (`//!`):
These comments are used to document the *enclosing* item (e.g., a module or the entire crate). They are placed at the top of a file or module to describe its overall purpose.
```rust
//! # My Awesome Crate
//!
//! This crate provides useful utilities for various tasks.
//! It includes functions for mathematical operations and string manipulation.
```

Best Practices for Comments:
* Focus on 'Why', not 'What': Good comments explain the *reasoning* behind the code, not merely restate what the code does (unless the code is particularly obscure).
* Keep Them Up-to-Date: Outdated comments are worse than no comments, as they can be misleading.
* Be Concise: Avoid overly verbose comments.
* Avoid Commenting Obvious Code: If the code is clear enough on its own, a comment is redundant.
* Use Documentation Comments Effectively: Leverage `///` and `//!` to make your code self-documenting for tools like `rustdoc`.

```rust
//! # Comments Example Crate
//! 
//! This crate demonstrates different types of comments in Rust,
//! including line comments, block comments, and documentation comments.

// This is a single-line comment. It explains the purpose of the code below.

/*
 * This is a multi-line block comment.
 * It's useful for providing more detailed explanations
 * or temporarily commenting out blocks of code.
 */

/// This function calculates the sum of two 32-bit signed integers.
///
/// # Arguments
///
/// * `x` - The first integer.
/// * `y` - The second integer.
///
/// # Returns
///
/// The sum of `x` and `y`.
///
/// # Examples
///
/// ```
/// let result = comments_example::add(5, 3);
/// assert_eq!(result, 8);
/// ```
pub fn add(x: i32, y: i32) -> i32 {
    // Perform the addition operation.
    let sum = x + y;

    // A block comment nested within another (less common but valid).
    /* This comment is also part of the 'add' function logic.
       It shows that block comments can be nested:
       /* Nested part */
    */

    sum // Return the calculated sum.
}

/// This is another example function that greets a given name.
///
/// # Arguments
///
/// * `name` - A string slice representing the name to greet.
///
/// # Returns
///
/// A `String` containing the greeting message.
pub fn greet(name: &str) -> String {
    format!("Hello, {}!", name) // Use string formatting to create the greeting.
}

fn main() {
    // Call the add function and print the result.
    let num1 = 10;
    let num2 = 20;
    let sum = add(num1, num2); // The 'add' function is documented using '///'.
    println!("The sum of {} and {} is: {}", num1, num2, sum);

    // Call the greet function and print the greeting.
    let person_name = "Alice";
    let greeting_message = greet(person_name);
    println!("{}", greeting_message);

    /*
       // This entire block of code is commented out.
       // It won't be executed by the Rust compiler.
       let unused_variable = 100;
       println!("This line will not be printed.");
    */
}
```