Documentation

Every program describes how to accomplish some task in the language of mathematics and logic. While high level languages help us to express programming concepts easily and clearly, they are often not the best way to explain the abstract concepts involved. This is where programming documentation comes to the rescue. Documentation in the form of program comments interspersed in the source code are a means to explain in plain English the expected workings of a program and the high level concepts involved. They are a way to include information that is not obvious or clear in the programming statements themselves.

In this site we will use a standard block of comments at the beginning of each file to explain the purpose of the program in the file. We will include the program author, the date that the program was written and any updates that were made. This last use of comments to document the update history is one that should only be used for programs that are not under source code control. For complex multi-file programs a [[source code control system]] will be a necessity and will perform the task of managing the update history of files.

Basic comments take two forms: single-line and multiple-line. Single-line comments begin with a double slash (//) and continue to the end of the current line. They can start at the beginning of the line or anywhere in the middle of a line. Multi-line comments may begin anywhere using the comment start symbol (/*) and continue until the comment end symbol (*/). All characters in the comment are ignored and not considered to be executable program content.

The following are examples of comments.

// This is a single line comment

/* This is an example
   of a multi-line comment */

Each program file, class or function/method should have a comment preceding it that describes the purpose and typical usage of the item being documented. Comments should document the high-level behavior and not get involved in the specifics of the current implementation. Implementation details can change but the interface described by the comment should rarely change. It also helps to know how the program, class or function/method is intended to perform when the code itself is found to have a bug. The following is an example of what a program file comment might look like.

/*********************************************************************
 * This program computes ...
 *
 * Copyright © 2023 Richard Lesh.  All rights reserved.
 ********************************************************************/

Modern Rust Documentation

Modern Rust documentation has two layers:

Human-facing guides: README, tutorials, architecture notes, examples
API/reference docs: generated from source using Rust documentation comments

What Should Be Documented

Modern Rust documentation should describe:

the purpose of a function, struct, enum, trait, module, or constant
ownership and borrowing expectations
preconditions and postconditions
error behavior
thread-safety and Send/Sync concerns when relevant
performance or complexity when relevant
examples of use

This aligns better with how modern Rust libraries are read and maintained. Rust has a built-in documentation syntax for documenting APIs using documentation comments. The rustdoc tool reads these comments directly from Rust source code and can generate HTML API documentation automatically.

Rust Documentation Comments

Rust uses outer documentation comments such as /// for items and inner documentation comments such as //! for documenting a module or crate. These comments are written in Markdown, so they can include headings, lists, code blocks, and links directly.

For example, a documentation comment for a function might look like this:

/// Computes the area of a circle.
///
/// Uses the standard formula pi * r^2.
///
/// # Arguments
///
/// * `radius` - Radius of the circle in meters. Must be non-negative.
///
/// # Returns
///
/// Area in square meters.
///
/// # Panics
///
/// Panics if `radius` is negative.
pub fn circle_area(radius: f64) -> f64 {
    assert!(radius >= 0.0, "radius must be non-negative");
    std::f64::consts::PI * radius * radius
}

This is a typical Rust documentation block. Unlike normal comments (// or /* */), this style signals to documentation tools that the text inside should be parsed and included in generated API documentation.

The comment is placed immediately before the function declaration, which tells rustdoc that the documentation applies to that function.

The first line provides a short summary of the function.

Most documentation systems display the summary description in:

function lists
summary tables
quick navigation views

The summary should explain what the function does, not how it works internally.

After the summary line, you can include additional explanatory text.

This section may describe:

the algorithm used
important assumptions
behavior that may not be obvious

rustdoc treats this as the detailed description of the function.

The # Arguments section documents each parameter of the function.

Good parameter documentation usually explains:

the meaning of the parameter
valid value ranges
units of measurement (if relevant)
any constraints or requirements

Each function parameter should normally be described clearly.

The # Returns section explains what value the function returns.

It should describe:

what the returned value represents
the units of the result if applicable
any special values that might be returned

Even if the return type is obvious from the code, describing the meaning of the result is helpful for readers.

The # Panics or # Errors section documents failure behavior.

It should include:

whether the function may panic
whether it returns a Result
the conditions under which an error occurs

This helps programmers understand the error conditions that must be handled when calling the function.

Structured comments like this serve several purposes:

Readable source code documentation
Automatically generated API reference manuals
Improved IDE tooltips and code navigation
Clear documentation of interface contracts

Tools such as rustdoc can scan these comments and generate HTML documentation directly from the source code.

Structs, enumerations, traits, generic types, and modules can also have documentation comments placed before them. For example:

Struct Example

/// Represents a bank account with a running balance.
///
/// Instances of this type are not thread-safe without external synchronization.
pub struct Account {
    balance: f64,
}

impl Account {
    /// Deposits money into the account.
    ///
    /// # Arguments
    ///
    /// * `amount` - Amount to deposit. Must be positive.
    pub fn deposit(&mut self, amount: f64) {
        self.balance += amount;
    }

    /// Returns the current balance.
    pub fn balance(&self) -> f64 {
        self.balance
    }
}

Enumeration Example

/// States a task can be in during execution.
pub enum TaskState {
    /// Task has not started yet.
    Pending,

    /// Task is currently executing.
    Running,

    /// Task finished successfully.
    Complete,

    /// Task ended with an error.
    Failed,
}

Generic Type Example

/// Returns the larger of two values.
///
/// # Type Parameters
///
/// * `T` - A type that supports comparison.
///
/// # Arguments
///
/// * `a` - First value.
/// * `b` - Second value.
///
/// # Returns
///
/// The larger of `a` and `b`.
pub fn max_value<T: PartialOrd>(a: T, b: T) -> T {
    if a >= b { a } else { b }
}

Generic comments in Rust usually describe type parameters in prose or in a section such as # Type Parameters. Trait bounds such as PartialOrd are also part of the signature and often deserve explanation if they are not obvious.

Rust also supports documenting modules and traits.

Module Example

//! Utility functions for common mathematical operations.

Trait Example

/// Defines a simple shape with an area.
pub trait Shape {
    /// Computes the area of the shape.
    fn area(&self) -> f64;
}

Modern docs are much easier to learn from when each API item includes a short usage example.

/// Converts a string to uppercase.
///
/// # Examples
///
/// ```
/// let s = to_upper("Hello");
/// assert_eq!(s, "HELLO");
/// ```
pub fn to_upper(text: &str) -> String {
    text.to_uppercase()
}

In Rust documentation comments, fenced Markdown code blocks are used to show examples.

These examples are especially powerful because rustdoc can often compile and test them as documentation tests.

This makes examples safer, more maintainable, and more useful for readers.

Generating Documentation with rustdoc

Once your Rust code contains documentation comments, you can automatically generate a browsable documentation website.

Generate Documentation with Cargo

If Rust and Cargo are installed, the easiest way to build documentation is with cargo doc.

Linux and
Raspberry Pi

$ cargo doc

macOS

% cargo doc

Windows

> cargo doc

This builds the crate documentation and any dependency documentation needed for linking.

Open the Documentation in a Browser

You can generate and open the documentation in one step:

Linux and
Raspberry Pi

$ cargo doc --open

macOS

% cargo doc --open

Windows

> cargo doc --open

This tells Cargo to build the documentation and then open the generated index.html file in your default browser.

Generate Documentation Without Dependencies

In larger projects, you may want to generate documentation only for your own crate:

$ cargo doc --no-deps

This tells Cargo to:

generate documentation for your crate
skip dependency documentation
reduce build time and clutter

View the Generated Documentation

The generated documentation will appear under the target/doc directory. Open the index.html file in a web browser to browse your project’s API documentation.

References

[[Rust Language Reference]]
[[Rust Compiler]]