Rustdoc: A Beginner's Guide for API Documentation in Rust

Documentation serves as the bridge between developers and the users of their code. In the Rust ecosystem, documentation is elevated to a first-class citizen through Rustdoc, a sophisticated documentation generation tool that ships with the standard Rust distribution. Unlike documentation tools in many other languages, Rustdoc doesn't merely generate static documentation—it creates interactive, testable, and richly formatted documentation websites that enhance code discoverability and usability.

For Rust developers, Apidog offers comprehensive API documentation features for HTTP APIs with interactive testing capabilities, visual response formatting, and collaborative functions.

Apidog focuses on documenting endpoints, request/response formats, and HTTP specifications, Rustdoc specializes in documenting code at the language level—documenting structs, functions, traits, and other programming constructs that make up a Rust crate. Both systems share the fundamental goal of making complex technical systems more accessible through thorough, accurate, and usable documentation.

What is Rustdoc?

Rustdoc is a command-line tool that parses Rust source code and special documentation comments to generate HTML, CSS, and JavaScript files that form a browsable documentation website. At its core, Rustdoc operates by extracting documentation comments from your code and transforming them into structured documentation.

The basic operation of Rustdoc involves:

1. Parsing Rust source files to extract documentation comments
2. Converting those comments from Markdown to HTML
3. Generating a searchable, navigable website structure
4. Extracting code examples from documentation and preparing them for testing
5. Creating cross-references between items
6. Producing static assets for the final documentation

When invoked directly, the Rustdoc binary accepts a Rust source file as input:

$ rustdoc src/lib.rs --crate-name my_crate

This command processes the lib.rs file and outputs documentation to a doc directory by default. The documentation is structured hierarchically, mirroring the structure of your code, with separate pages for modules, structs, enums, traits, and other Rust constructs.

Under the hood, Rustdoc leverages the Rust compiler's internal APIs to parse and understand your code. This tight integration with the compiler enables Rustdoc to generate accurate cross-references, properly document type signatures, and verify that code examples actually compile and run correctly.

Documentation Comments in Rust

Documentation in Rust relies on special comment syntax that differs from regular code comments. There are two primary types of documentation comments:

Outer Documentation Comments (///)

Outer documentation comments document the item that follows them and are denoted by three forward slashes:

/// This is a documentation comment for the function below.
/// It can span multiple lines and supports Markdown formatting.
pub fn documented_function() -> bool {
    true
}

These comments describe functions, structs, enums, traits, modules, and other items in your codebase. They're called "outer" documentation because they exist outside the item they document.

Inner Documentation Comments (//!)

Inner documentation comments document the item they appear within and are denoted by //!:

//! This module provides utilities for parsing configuration files.
//!
//! # Examples
//!
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // Implementation here
}

Inner documentation comments are commonly used for module-level or crate-level documentation. When placed at the beginning of a lib.rs file, they document the entire crate and form the front page of your generated documentation.

The technical difference between these comment styles is subtle but important: /// documents what comes after it, while //! documents what contains it.

Markdown Support in Rustdoc

Rustdoc uses a CommonMark-compliant Markdown parser with several extensions. This gives documentation authors access to a rich set of formatting options:

Basic Formatting

/// # Heading Level 1
/// ## Heading Level 2
///
/// Paragraphs are separated by blank lines.
///
/// *Italic text* and **bold text** are supported.
///
/// - Unordered lists
/// - Can be created
/// - Like this
///
/// 1. Ordered lists
/// 2. Work as well
///
/// `Inline code` is surrounded by backticks.

Code Blocks

Code blocks are particularly important in Rustdoc as they serve dual purposes: they display code examples in the documentation and can be extracted as tests.

/// ```rust
/// // This is a code block
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

By default, if no language is specified after the opening triple backticks, Rustdoc assumes the code block contains Rust code. However, you can specify other languages for syntax highlighting:

/// ```json
/// {
///     "name": "example",
///     "version": "1.0.0"
/// }
/// ```

Rustdoc Extensions

Rustdoc extends CommonMark with several additional features:

Strikethrough Text

/// ~~Strikethrough text~~ uses tildes.

Footnotes

/// This statement needs clarification[^1].
///
/// [^1]: Here's the clarification.

Tables

/// | Header1 | Header2 |
/// |---------|---------|
/// | cell1   | cell2   |
/// | cell3   | cell4   |

Task Lists

/// - [x] Completed task
/// - [ ] Incomplete task

Smart Punctuation

Rustdoc automatically converts ASCII punctuation sequences to their Unicode equivalents:

• -- becomes en dash (–)
• --- becomes em dash (—)
• ... becomes ellipsis (…)
• Straight quotes become curly quotes

Detailed Rustdoc Command-line Interface

Rustdoc offers a comprehensive set of command-line options for customizing documentation generation:

$ rustdoc --help

Some of the most technically significant options include:

• --document-private-items: By default, Rustdoc only documents public items. This flag includes private items in the documentation, useful for internal documentation.
• --test: Run documentation examples as tests, verifying they compile and execute as expected.
• --test-args: Pass additional arguments to the test runner, such as --nocapture to show output from tests.
• --edition=EDITION: Specify the Rust edition for parsing and running the code (2015, 2018, 2021, 2024).
• --target=TARGET: Generate documentation for the specified target platform.
• --crate-type=TYPE: Specify the crate type for tests (bin, lib, rlib, dylib, cdylib, staticlib, proc-macro).
• -L FLAG=PATH: Add a directory to the library search path, crucial for resolving dependencies in tests.
• --cfg=SPEC: Pass a --cfg flag to the compiler, enabling conditional compilation in documentation code.
• --extern NAME=PATH: Specify the location of an external crate, allowing tests to reference external dependencies.

For a project with external dependencies, a typical Rustdoc invocation might look like:

$ rustdoc src/lib.rs --crate-name example_crate \
  --edition=2021 \
  -L dependency=target/debug/deps \
  --extern serde=target/debug/deps/libserde-abcd1234.rlib \
  --extern tokio=target/debug/deps/libtokio-efgh5678.rlib

Fortunately, Cargo automates this complex process with a simple command:

$ cargo doc --document-private-items

Integration with Cargo

Cargo provides a streamlined interface for working with Rustdoc through the cargo doc command. Internally, Cargo calls Rustdoc with the appropriate parameters:

$ cargo doc --verbose

Running this command will display the actual Rustdoc invocation, revealing how Cargo configures paths to dependencies and output directories.

The core functionality includes:

• cargo doc: Generate documentation for the current crate and its dependencies
• cargo doc --no-deps: Generate documentation only for the current crate
• cargo doc --open: Generate documentation and open it in a web browser
• cargo doc --document-private-items: Include private items in the documentation
• cargo test --doc: Run documentation tests

Cargo intelligently determines the crate name from your Cargo.toml file, sets up the correct output directory structure under target/doc/, and ensures all dependencies are properly linked.

Documentation Structure and Organization

Crate-level Documentation

The crate-level documentation serves as the landing page for your library and should provide a comprehensive overview. This is written as inner documentation (//!) at the top of the lib.rs file:

//! # My Advanced Cryptography Library
//!
//! This crate provides cryptographic primitives with a focus on:
//!
//! - **Performance**: Optimized implementations for modern CPUs
//! - **Security**: Formally verified algorithms
//! - **Usability**: High-level, hard-to-misuse APIs
//!
//! ## Quick Start
//!
//! ```rust
//! use crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"Secret message";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## Features
//!
//! The crate supports the following algorithms:
//!
//! - AES (128, 192, 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

Effective crate-level documentation often includes:

1. A concise, one-sentence description of the crate's purpose
2. Detailed explanation of key concepts and features
3. Quick-start examples showing basic usage
4. Architecture overview for more complex libraries
5. Feature flags and configuration options
6. Compatibility information
7. Performance characteristics

Module-level Documentation

Modules act as organizational units in Rust and should have their own documentation that explains their purpose and contents:

pub mod symmetric {
    //! Symmetric encryption algorithms.
    //!
    //! This module provides implementations of block and stream ciphers,
    //! authenticated encryption algorithms, and related utilities.
    //!
    //! # Security Considerations
    //!
    //! All implementations have been audited by [Security Firm]
    //! and formally verified using [Verification Tool].

    /// AES block cipher implementation with support for 128, 192, and 256-bit keys.
    pub struct Aes {
        // Fields here
    }

    // More items...
}

Item-level Documentation

Individual items like structs, functions, and traits should have focused documentation that explains their purpose, usage, and any special considerations:

/// A cryptographically secure random number generator.
///
/// This CSPRNG uses the system's entropy source to generate
/// random bytes suitable for cryptographic operations.
///
/// # Examples
///
/// ```
/// use crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # Security
///
/// On Linux, this uses getrandom(2) when available, falling back to /dev/urandom.
/// On Windows, it uses BCryptGenRandom.
/// On macOS, it uses SecRandomCopyBytes.
pub struct CSPRNG {
    // Implementation details
}

impl CSPRNG {
    /// Creates a new cryptographically secure random number generator.
    ///
    /// # Panics
    ///
    /// Panics if the system's entropy source is unavailable.
    ///
    /// # Examples
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // Implementation
    }

    /// Generates the specified number of random bytes.
    ///
    /// # Arguments
    ///
    /// * `len` - The number of random bytes to generate
    ///
    /// # Returns
    ///
    /// A vector containing `len` cryptographically secure random bytes.
    ///
    /// # Examples
    ///
    /// ```
    /// use crypto_lib::CSPRNG;
    ///
    /// let mut rng = CSPRNG::new();
    /// let key_material = rng.generate_bytes(32);
    /// assert_eq!(key_material.len(), 32);
    /// ```
    pub fn generate_bytes(&mut self, len: usize) -> Vec<u8> {
        // Implementation
    }
}

Documentation Tests in Depth

One of Rustdoc's most powerful features is its ability to run code examples as tests. This ensures that:

1. Examples in your documentation actually compile
2. Examples produce the expected results
3. Examples stay up-to-date as your API evolves

When you include a Rust code block in your documentation, Rustdoc extracts it and creates a test harness around it:

/// Adds two numbers.
///
/// # Examples
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Behind the scenes, Rustdoc transforms this into a standalone test file resembling:

extern crate my_crate;

fn main() {
    let result = my_crate::add(2, 3);
    assert_eq!(result, 5);
}

This file is then compiled and executed. If the program compiles and runs without panicking, the test passes.

Test Preprocessing

Before running the test, Rustdoc applies several transformations to make simple examples more ergonomic:

1. Common lints like unused_variables and dead_code are allowed
2. If the example doesn't contain extern crate and #![doc(test(no_crate_inject))] wasn't specified, extern crate <mycrate>; is inserted
3. If the example doesn't contain fn main, the code is wrapped in fn main() { ... }

These transformations allow you to focus on the important parts of your example without boilerplate.

Controlling Test Behavior

Rustdoc provides several attributes to control how tests are executed:

• ignore: The code is not tested
• should_panic: The code should compile but panic when run
• compile_fail: The code should not compile
• no_run: The code is compiled but not executed
• edition2015, edition2018, edition2021: Run the code with a specific Rust edition

Examples:

/// ```ignore
/// // This code isn't tested
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // This code should panic
/// panic!("This example demonstrates a panic");
/// ```
///
/// ```compile_fail
/// // This code shouldn't compile
/// let x: i32 = "this should not compile";
/// ```
///
/// ```no_run
/// // This code compiles but doesn't run
/// loop {
///     println!("This would run forever!");
/// }
/// ```
///
/// ```edition2021
/// // This code uses Rust 2021 features
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

Using ? in Doc Tests

Since documentation examples are wrapped in a main() function that returns (), using the ? operator requires special handling. There are two approaches:

1. Explicitly define a main function that returns a Result:

/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok(())
/// # }
/// ```

2. Use a type annotation with Ok(()):

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

In both cases, the # at the beginning of some lines hides them from the rendered documentation but includes them in the test.

Linking to Items by Name

Rustdoc provides a powerful cross-referencing system that allows documentation authors to create links to other items in the codebase. This feature significantly enhances the navigability of your documentation.

Intra-doc Links

To create a link to another item, use the syntax [item_name]:

/// Uses the [`HashMap`] type from the standard library.
///
/// It also relies on the [`build_map`] function defined elsewhere in this crate.
pub fn process_data() {
    // Implementation
}

/// Constructs a new [`HashMap`] with predefined values.
pub fn build_map() -> HashMap<String, i32> {
    // Implementation
}

When Rustdoc processes these links, it automatically resolves them to the correct items, creating clickable hyperlinks in the generated HTML.

Path Qualification

For more precise linking, especially when dealing with items that might have the same name in different modules, you can use fully qualified paths:

/// This function uses [`std::collections::HashMap`] for storage
/// and [`crate::utils::format`] for formatting the output.
pub fn complex_operation() {
    // Implementation
}

The path resolution follows Rust's visibility rules, so you can only link to items that would be visible from the current scope.

Link Targets

You can link to various kinds of items:

/// Links to a struct: [`MyStruct`]
/// Links to an enum: [`Option`]
/// Links to a trait: [`Iterator`]
/// Links to a function: [`process_data`]
/// Links to a method: [`MyStruct::new`]
/// Links to a module: [`crate::utils`]
/// Links to a constant: [`MAX_SIZE`]
/// Links to a type alias: [`Result`]

This comprehensive linking system allows documentation authors to create a rich web of interconnected documentation that helps users navigate complex APIs.

Advanced Documentation Features

The #[doc] Attribute

The #[doc] attribute provides advanced control over documentation generation:

// Equivalent to using /// comments
#[doc = "This is documentation for the item below."]
pub struct DocumentedStruct;

// Hide an item from documentation
#[doc(hidden)]
pub struct InternalStruct;

// Add search aliases
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

For conditional documentation based on feature flags:

/// This function does amazing things.
#[doc = "Basic capability explanation."]
#[cfg_attr(feature = "advanced", doc = "Also supports advanced mode when the 'advanced' feature is enabled.")]
pub fn do_things() {
    // Implementation
}

Documentation Include Patterns

For reusing content across documentation:

/// # Safety
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // Implementation
}

This allows you to maintain common documentation segments in separate files and include them where needed, reducing duplication and ensuring consistency.

Scraped Examples

Rustdoc can automatically extract code examples from your crate's tests and examples directories, providing additional context for API usage:

$ cargo doc --document-scraped-examples

This feature works by scanning your crate for usage of public items and extracting those usages as examples. It's particularly valuable for complex APIs where inline documentation examples might be insufficient.

Conditional Documentation

Using cfg attributes, you can conditionally include or exclude documentation:

#[cfg(target_os = "windows")]
/// Windows-specific implementation details.
pub fn windows_only_function() {
    // Windows implementation
}

#[cfg(target_os = "linux")]
/// Linux-specific implementation details.
pub fn linux_only_function() {
    // Linux implementation
}

This allows you to create platform-specific or feature-specific documentation that only appears when relevant.

Custom HTML in Documentation

For special formatting needs, Rustdoc allows embedding HTML directly in documentation:

/// <div class="warning">
/// <strong>Warning:</strong> This function performs I/O and may block.
/// </div>
pub fn blocking_operation() {
    // Implementation
}

Combined with custom CSS, this enables rich formatting beyond what Markdown alone provides.

Custom HTML and CSS

Rustdoc allows customization of the generated documentation's appearance through HTML and CSS:

HTML Preprocessing

You can add custom HTML to the documentation header:

$ rustdoc src/lib.rs --html-in-header custom-header.html

This is useful for adding custom stylesheets, JavaScript libraries, or meta tags.

CSS Customization

To apply custom CSS to your documentation:

$ rustdoc src/lib.rs --css custom-styles.css

Your CSS file can target Rustdoc's HTML structure to customize colors, fonts, layouts, and more:

/* Change the main background color */
body {
    background-color: #f5f5f5;
}

/* Style warning blocks */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* Custom styling for code blocks */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

Custom Rendering Themes

Rustdoc supports multiple built-in themes, including Light, Rust, Coal, Navy, and Ayu. You can also create custom themes:

$ rustdoc src/lib.rs --theme mytheme.css

Documentation Best Practices

Technical Accuracy

Documentation must be technically precise. Specify exact behavior, edge cases, and performance characteristics:

/// Searches for an element in a sorted slice using binary search.
///
/// # Complexity
///
/// Time complexity: O(log n)
/// Space complexity: O(1)
///
/// # Panics
///
/// Panics if the slice is not sorted in ascending order.
///
/// # Examples
///
/// ```
/// let sorted = [1, 2, 3, 4, 5];
/// assert_eq!(my_crate::binary_search(&sorted, 3), Some(2));
/// assert_eq!(my_crate::binary_search(&sorted, 6), None);
/// ```
pub fn binary_search<T: Ord>(slice: &[T], value: T) -> Option<usize> {
    // Implementation
}

Structured Documentation

Follow a consistent structure for each type of item:

Functions and methods:

• Short description
• Parameter explanations
• Return value description
• Error cases
• Panics section (if applicable)
• Examples
• Performance characteristics
• Safety considerations (for unsafe functions)

Structs and enums:

• Purpose and high-level description
• Field/variant explanations
• Construction methods
• Common operations
• Examples of typical usage

Traits:

• Contract and guarantees
• Required methods explanation
• Provided methods documentation
• Implementation guidance
• Examples showing implementation and usage

Language Precision

Use precise technical language and avoid ambiguity:

• Instead of "fast," specify "O(log n) time complexity"
• Instead of "memory efficient," specify "uses constant stack space"
• Instead of "might fail," specify exact error conditions
• Instead of "large inputs," specify concrete limitations

Versioning Information

Document API stability and versioning considerations:

/// Processes network packets according to RFC 1234.
///
/// # Stability
///
/// This function is considered stable since version 0.2.0.
///
/// # Version Differences
///
/// Prior to 0.3.0, this function would silently truncate packets
/// larger than 1500 bytes. Now it returns an error.
pub fn process_packet(packet: &[u8]) -> Result<ProcessedPacket, PacketError> {
    // Implementation
}

Advanced Testing Techniques

Testing in Different Environments

You can configure documentation tests to run with specific environment variables:

/// ```
/// # std::env::set_var("API_KEY", "test_key");
/// let client = my_crate::Client::new_from_env()?;
/// # Ok::<(), my_crate::Error>(())
/// ```

Testing with External Resources

For tests that need external resources, use the no_run attribute and explain the requirements:

/// ```no_run
/// // This example requires a PostgreSQL database at localhost:5432
/// // with username "test" and password "test"
/// let db = my_crate::Database::connect(
///     "postgres://test:test@localhost:5432/testdb"
/// )?;
/// # Ok::<(), my_crate::Error>(())
/// ```

Testing Error Handling

Show how errors are handled in your API:

/// ```
/// use my_crate::{process_data, DataError};
///
/// // Successful case
/// let result = process_data(&[1, 2, 3]);
/// assert!(result.is_ok());
///
/// // Error case
/// let error_result = process_data(&[]);
/// assert!(matches!(error_result, Err(DataError::EmptyInput)));
/// ```

Internationalization and Accessibility

Non-English Documentation

While Rustdoc doesn't have built-in internationalization support, you can provide documentation in multiple languages using feature flags:

#[cfg(feature = "docs-en")]
/// Adds two numbers together.
#[cfg(feature = "docs-es")]
/// Suma dos números.
#[cfg(feature = "docs-ja")]
/// 二つの数値を足します。
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Accessibility Considerations

Write documentation that's accessible to users with disabilities:

1. Provide text alternatives for images
2. Use sufficient color contrast
3. Structure content with proper headings
4. Make code examples screen-reader friendly

/// The architecture diagram below illustrates the system components:
///
/// ![Architecture Diagram](./images/architecture.png)
/// *Alt text: A flowchart showing data flow from Input through Processing to Output,
/// with Database and Cache components on the sides*

Conclusion

Rustdoc stands as one of the most powerful and comprehensive documentation tools in any programming language ecosystem. Its tight integration with the Rust compiler, robust testing capabilities, and rich formatting options enable developers to create documentation that is not just descriptive but also accurate, usable, and maintainable.

By leveraging the full capabilities of Rustdoc—from basic documentation comments to advanced features like conditional compilation, custom HTML/CSS, and comprehensive testing—Rust developers can create documentation that serves as both a learning resource and a reliable reference.

Documentation is a fundamental aspect of API design and software usability. When crafted with care and technical precision using Rustdoc's capabilities, it becomes an invaluable asset that reduces the learning curve, prevents errors, and promotes correct usage of your libraries.

As the Rust ecosystem continues to evolve, Rustdoc evolves with it, consistently improving its capabilities to meet the needs of an increasingly diverse and sophisticated user base. By mastering Rustdoc, you not only improve your own codebase but also contribute to the high documentation standards that help make the Rust community one of the most welcoming and accessible in the programming world.

Frequently Asked Questions

1. How can I debug documentation tests that are failing?

Answer: Documentation tests can be debugged using several techniques:

Run tests with more output:

cargo test --doc -- --nocapture

Add print statements to your test (they'll be hidden in documentation but visible during test runs):

/// ```
/// let result = my_crate::complex_function();
/// # println!("Debug: result = {:?}", result);
/// assert!(result.is_ok());
/// ```

Use the -test-args flag to pass additional options:

cargo test --doc -- --test-args=--show-output

Create a standalone reproduction of your test in a separate file for easier debugging.

If you're using feature flags that might affect the test, make sure they're enabled:

cargo test --doc --features=my-feature

2. How do I document unsafe code properly?

Answer: Documenting unsafe code requires special attention to safety requirements:

1. Always include a dedicated "Safety" section that clearly states all invariants that callers must uphold.
2. Detail the undefined behavior that may result if safety requirements aren't met.
3. Explain why the function needs to be unsafe and cannot be safely implemented.
4. Provide examples showing both correct and incorrect usage (use compile_fail for the latter).

Example:

/// Dereferences a raw pointer.
///
/// # Safety
///
/// The caller must ensure that:
/// - The pointer is properly aligned for the type T
/// - The pointer points to an initialized instance of T
/// - The pointer is valid for reads for the size of T
/// - No other references to the same memory exist while this function executes
///
/// Violating any of these conditions leads to undefined behavior.
///
/// # Examples
///
/// Safe usage:
/// ```
/// let value = 42;
/// let ptr = &value as *const i32;
/// unsafe {
///     assert_eq!(my_crate::deref(ptr), 42);
/// }
/// ```
///
/// ```compile_fail
/// // This would cause undefined behavior:
/// let ptr = 0x1234 as *const i32;
/// unsafe {
///     my_crate::deref(ptr); // Invalid pointer!
/// }
/// ```
pub unsafe fn deref<T>(ptr: *const T) -> T {
    *ptr
}

3. How do I create documentation that is conditionally compiled based on feature flags?

Answer: You can use #[cfg_attr] and other conditional compilation directives:

/// This function always has basic documentation.
#[cfg_attr(feature = "extended-docs", doc = " It also has detailed performance analysis when the 'extended-docs' feature is enabled.")]
#[cfg_attr(feature = "examples", doc = "
# Advanced Examples

#[cfg_attr(feature = "examples", doc = "let result = complex_computation(1000);")] #[cfg_attr(feature = "examples", doc = "assert!(result < 0.001);")] #[cfg_attr(feature = "examples", doc = "```")] pub fn complex_computation(iterations: usize) -> f64 { // Implementation }

Generate documentation with features enabled:
```bash
cargo doc --features="extended-docs examples"

Alternative approach for larger conditional documentation:

/// Basic documentation for all builds
#[cfg(not(feature = "full-docs"))]
pub struct ApiClient;

/// Basic documentation for all builds
///
/// # Detailed Authentication Process
///
/// When authenticating, the client performs these steps:
/// 1. Validate credentials
/// 2. Generate a secure token
/// 3. Establish encrypted channel
///
/// [...]
#[cfg(feature = "full-docs")]
pub struct ApiClient;

4. How can I measure and improve documentation coverage?

Answer: Documentation coverage can be improved using several techniques:

Use the #[warn(missing_docs)] attribute at the crate level to get warnings for undocumented public items:

#![warn(missing_docs)]

Add #[deny(missing_docs)] to make undocumented public items a compilation error.

Use third-party tools like cargo-spellcheck to check documentation quality.

Create a CI check that runs rustdoc with the D warnings flag to fail if documentation is missing:

RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

Consider implementing a documentation review as part of your PR process, focusing on:

• Every public item having documentation
• Every function having at least one example
• All parameters and return values being explained
• Error cases and panics being documented

5. How do I create multi-file documentation with custom organization?

Answer: For complex documentation needs that go beyond API docs:

Use separate Markdown files for conceptual documentation and guides:

//! See the [User Guide](../docs/user_guide.md) for more information.

Create a central hub with #[doc = include_str!()]:

//! # My Comprehensive Library
//!
#[doc = include_str!("../docs/overview.md")]
//!
//! ## Guides
//!
#[doc = include_str!("../docs/installation.md")]
#[doc = include_str!("../docs/quick_start.md")]
//!
//! ## API Reference
//! The sections below detail the public API.

Use the #[doc(hidden)] attribute to hide implementation modules while keeping them public:

/// Public API for network operations
pub mod network {
    // Public API items here

    #[doc(hidden)]
    pub mod internals {
        // Implementation details that should be
        // public but not in documentation
    }
}

For complex projects, consider creating a separate documentation crate with mdBook that references your API docs:

# Install mdBook
cargo install mdbook

# Create a new book
mdbook init my-project-book

# Build both API docs and book
cargo doc
cd my-project-book && mdbook build

Then link between them using relative HTML paths.