Documentation in Rust: Advanced Techniques and Tools

Introduction: Why Documentation in Rust is More Than Just Comments

The Rust ecosystem is known for its strictness and reliability. However, even the most elegant code is useless without quality documentation. At a basic level, it's enough to write a couple of lines of /// for public functions. But when your project grows to several crates with dozens of modules, the question of advanced documentation techniques arises.

In this article, we will look at tools and techniques that will help you create enterprise-level documentation: from automatic testing of examples to generating books and integrating with CI/CD.

1. Doctests: Documentation That Doesn't Lie

The main "feature" of rustdoc is the ability to embed executable code examples directly into comments. Such examples are automatically compiled and run when you execute cargo test. This ensures that your documentation is always up-to-date.

Basic doctest

/// Returns the sum of two numbers.\n///\n/// # Example\n///\n/// ```\n/// let result = my_crate::add(2, 3);\n/// assert_eq!(result, 5);\n/// ```\npub fn add(a: i32, b: i32) -> i32 {\n    a + b\n}

Advanced doctest techniques

You can hide setup lines that should not be displayed in the documentation using # :

/// # Example with initialization\n///\n/// ```\n/// # use std::collections::HashMap;\n/// let mut map = HashMap::new();\n/// map.insert("key", 42);\n/// assert_eq!(map.get("key"), Some(&42));\n/// ```

You can also check that code does not compile (for example, demonstrating compile-time errors):

/// ```compile_fail\n/// let x: i32 = "string"; // Error: type mismatch\n/// ```

2. Documentation Attributes: Control and Metadata

The #[doc(...)] attributes allow you to fine-tune the display of documentation.

Hiding items

/// Internal function, not intended for public use.\n#[doc(hidden)]\npub fn internal_helper() {}

Categorization and search

/// A group of utilities for working with the network.\n#[doc(alias = "net")]\n#[doc(alias = "socket")]\npub mod network {\n    // ...\n}

Embedding documentation from another location

/// See the [module documentation](index.html) for general information.\n#[doc(include = "docs/faq.md")]\npub fn complex_function() {}

3. Cross-references and Navigation

Rustdoc supports links to other documentation items. This creates a coherent structure that is easy to read.

Links to functions and types

/// Use [`Config::new`] to create an instance.\n///\n/// For more complex configuration, refer to the [`config`] module.\npub struct Config { /* ... */ }

Links to external crates

/// This function uses [serde_json] for serialization.\n///\n/// [serde_json]: https://docs.rs/serde_json\npub fn to_json() {}

4. Tools for Large Projects: mdBook and Crate Documentation

When a single cargo doc is no longer enough, mdBook comes to the rescue — a utility for creating books from Markdown files. It is ideal for writing guides, tutorials, and architectural documentation.

Quick start with mdBook

# Installation\ncargo install mdbook\n\n# Creating a project\nmdbook init my-book\ncd my-book\nmdbook serve --open

Integration with rustdoc

You can embed documentation from mdBook into cargo doc using the #[doc = include_str!()] attribute:

/// # Architecture\n///\n/// Detailed description of the library architecture:\n///\n#[doc = include_str!("../docs/architecture.md")]\npub mod core {\n    // ...\n}

Conclusion