Learn Rust Coding · Lesson

Doc Comments

/// documentation.

Doc Comments is a free Learn Rust Coding lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Learn Rust Coding learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Documentation in Rust

Rust has first-class documentation built into the language. Special comments become HTML docs generated by cargo doc.

Outer Doc Comments

Use /// to document the item that follows it — functions, structs, enums, and more. The text supports Markdown.

/// Adds two numbers together.
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Markdown Formatting

Doc comments render Markdown: headings, lists, bold, and links all work. Inline code uses backticks, and section headings start with #.

/// Computes the area of a rectangle.
///
/// # Arguments
/// * width - the width
/// * height - the height
pub fn area(width: u32, height: u32) -> u32 {
    width * height
}

Common Doc Sections

Conventional headings make docs scannable:

# Examples — usage samples
# Panics — when it panics
# Errors — what errors it returns
# Safety — invariants for unsafe code

Inner Doc Comments

Use //! to document the enclosing item, typically a module or the whole crate. Place it at the top of the file.

//! # My Math Crate
//!
//! Utilities for basic arithmetic.

pub fn double(n: i32) -> i32 {
    n * 2
}

Documenting Structs and Fields

Each public item, including struct fields, can have its own doc comment.

/// A point in 2D space.
pub struct Point {
    /// The horizontal coordinate.
    pub x: f64,
    /// The vertical coordinate.
    pub y: f64,
}

Generating Docs

cargo doc builds HTML documentation into target/doc. Add --open to view it in your browser.

cargo doc --open

Excluding Dependencies

By default Cargo also documents your dependencies. Use --no-deps to build docs for your crate only.

cargo doc --no-deps --open

Intra-Doc Links

Link to other items by writing their path inside square brackets. Rust resolves the path and creates a clickable link in the generated docs.

/// See also [add] for addition.
///
/// [add]: crate::add
pub fn subtract(a: i32, b: i32) -> i32 {
    a - b
}

Why Document?

Good docs pay off:

Generated automatically into searchable HTML
Published to docs.rs for free when you publish a crate
Examples in docs are tested (doc tests)
Helps teammates and future you

Documenting a Module

Combine inner and outer comments: a module file opens with //! describing the module, and each item inside uses ///.

//! Geometry helpers.

/// Returns the perimeter of a square.
pub fn perimeter(side: f64) -> f64 {
    side * 4.0
}

Quick Check

Which comment syntax documents the item that comes right after it?

Recap

You learned doc comments:

/// documents the following item; //! documents the enclosing one
They support Markdown and sections like # Examples
Intra-doc links connect items
cargo doc --open generates and views HTML docs

Frequently asked questions

Is the “Doc Comments” lesson free?

Yes — the full text of “Doc Comments” is free to read here on the web, and the Learn Rust Coding course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Learn Rust Coding course, upgrade to CoddyKit PRO.

What will I learn in “Doc Comments”?

/// documentation. You practise Learn Rust Coding with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Learn Rust Coding?

No prior experience is required. Learn Rust Coding on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Doc Comments” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Learn Rust Coding lesson?

Yes. Every Learn Rust Coding lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Learn Rust Coding