Documentation in Rust

In this lesson, you will learn how to write clear, professional documentation for Rust code. Good documentation helps others understand your code and makes your projects easier to maintain.

Rust provides a built-in documentation tool called Rustdoc, which generates HTML documentation directly from your source code.

Why Documentation Is Important

Documentation helps:

• Explain what your code does
• Make APIs easier to use
• Improve collaboration in teams
• Increase project quality and professionalism

In Rust, documentation is treated as a first-class feature.

What Is Rustdoc?

Rustdoc is Rust’s official documentation generator. It reads special comments in your code and produces readable HTML documentation.

Rustdoc is included automatically when you install Rust.

Documentation Comments

Rust uses special comments for documentation:

• /// – for documenting items (functions, structs, enums)
• //! – for documenting modules or crates

Documenting Functions

You can document a function using /// comments placed above it.

/// Adds two numbers together.
///
/// # Arguments
/// * `a` - First number
/// * `b` - Second number
///
/// # Returns
/// The sum of `a` and `b`
fn add(a: i32, b: i32) -> i32 {
    a + b
}

Markdown in Documentation

Rust documentation supports Markdown. This allows you to format text using headings, lists, and code blocks.

/// # Example
/// ```
/// let result = add(2, 3);
/// assert_eq!(result, 5);
/// ```

This example code appears directly inside the generated documentation.

Documenting Modules

Use //! to document entire modules or crates.

//! This module provides mathematical utilities.
//!
//! It includes functions for addition and subtraction.

Documenting Structs

You can document structs and their fields.

/// Represents a user in the system.
struct User {
    /// User name
    name: String,
    /// User age
    age: u32,
}

Documenting Enums

Enums can also be documented for clarity.

/// Represents application status.
enum Status {
    /// Operation succeeded
    Success,
    /// Operation failed
    Failure,
}

Generating Documentation

You can generate HTML documentation using Cargo.

cargo doc

This command generates documentation in the target/doc directory.

Opening Documentation in Browser

Cargo can automatically open documentation in your browser.

cargo doc --open

Documentation Tests

Rust can run tests written inside documentation examples.

/// ```
/// let x = 2 + 2;
/// assert_eq!(x, 4);
/// ```

These examples are executed when you run:

cargo test

Best Practices for Rust Documentation

• Explain what the code does
• Describe inputs and outputs
• Include examples
• Keep explanations clear and concise

📝 Practice Exercises

Exercise 1

Write documentation for a function that multiplies two numbers.

Exercise 2

Document a struct with two fields.

Exercise 3

Add a documentation example to a function.

Exercise 4

Generate and open documentation using Cargo.

✅ Practice Answers

Answer 1

/// Multiplies two numbers.
fn multiply(a: i32, b: i32) -> i32 {
    a * b
}

Answer 2

/// Represents a product.
struct Product {
    /// Product name
    name: String,
    /// Product price
    price: f64,
}

Answer 3

/// # Example
/// ```
/// let result = multiply(2, 3);
/// assert_eq!(result, 6);
/// ```

Answer 4

cargo doc --open

What’s Next?

In the next lesson, you will explore Concurrency in Rust, learning how Rust enables safe multi-threaded programming.