leonardomso__rust-skills/rules/doc-module-inner.md

doc-module-inner

Use //! for module-level documentation

Why It Matters

Inner doc comments (//!) document the module itself, not the next item. They appear at the top of module files and describe the module's purpose, contents, and usage patterns. This helps users understand what a module provides before diving into individual items.

Module docs are the first thing users see in cargo doc when navigating to a module.

Bad

// This module handles authentication
// It provides JWT and session-based auth

mod auth;

pub use auth::*;

// auth.rs
/// Authentication utilities  // Wrong: this documents nothing useful
use std::collections::HashMap;

pub struct Session { /* ... */ }

Good

//! Authentication and authorization utilities.
//!
//! This module provides multiple authentication strategies:
//!
//! - [`JwtAuth`] - JSON Web Token based authentication
//! - [`SessionAuth`] - Cookie-based session authentication
//! - [`ApiKeyAuth`] - API key authentication for services
//!
//! # Examples
//!
//! ```
//! use my_crate::auth::{JwtAuth, Authenticator};
//!
//! let auth = JwtAuth::new("secret-key");
//! let token = auth.generate_token(&user)?;
//! ```
//!
//! # Feature Flags
//!
//! - `jwt` - Enables JWT authentication (enabled by default)
//! - `sessions` - Enables session-based authentication

use std::collections::HashMap;

pub struct Session { /* ... */ }

Where to Use Inner Docs

Location	Purpose
lib.rs	Crate-level documentation (appears on crate root)
mod.rs	Module documentation for directory modules
module.rs	Module documentation for single-file modules

Crate Root Example

//! # My Awesome Crate
//!
//! `my_crate` provides utilities for handling complex workflows.
//!
//! ## Quick Start
//!
//! ```rust
//! use my_crate::prelude::*;
//!
//! let workflow = Workflow::builder()
//!     .add_step(Step::new("fetch"))
//!     .add_step(Step::new("process"))
//!     .build();
//! ```
//!
//! ## Modules
//!
//! - [`workflow`] - Core workflow engine
//! - [`steps`] - Built-in workflow steps
//! - [`prelude`] - Common imports
//!
//! ## Feature Flags
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `async` | Async workflow execution |
//! | `serde` | Serialization support |

pub mod workflow;
pub mod steps;
pub mod prelude;

Key Sections for Module Docs

1. Brief description - One-line summary
2. Overview - What the module provides
3. Examples - How to use it
4. Feature flags - Optional functionality
5. See Also - Related modules

See Also

• doc-all-public - Documenting public items
• doc-examples-section - Adding examples
• doc-cargo-metadata - Crate metadata