mirror of https://github.com/leonardomso/rust-skills.git synced 2026-09-14 19:33:21 +08:00

Files

T

Leonardo Maldonado 0016d5cfb2 Add comprehensive Rust best practices skill with 179 rules

Includes rules for:
- Ownership and borrowing patterns
- Error handling with thiserror/anyhow
- Memory management and allocation
- API design following Rust guidelines
- Async/Tokio patterns
- Performance optimization
- Naming conventions
- Type safety
- Testing strategies
- Documentation standards
- Project structure
- Linting configuration
- Common anti-patterns to avoid

2026-01-19 10:23:19 -03:00

2.9 KiB

Raw Blame History

lint-missing-docs

Warn on missing documentation for public items

Why It Matters

The missing_docs lint ensures all public API items are documented. For libraries, documentation IS the user interface. Missing docs mean users can't understand your API without reading source code.

Configuration

// In lib.rs
#![warn(missing_docs)]

Or in Cargo.toml:

[lints.rust]
missing_docs = "warn"

For strict enforcement:

#![deny(missing_docs)]

What It Catches

#![warn(missing_docs)]

pub struct User {  // WARN: missing documentation for a struct
    pub name: String,  // WARN: missing documentation for a field
    pub age: u32,      // WARN: missing documentation for a field
}

pub fn process() { }  // WARN: missing documentation for a function

pub trait Handler {  // WARN: missing documentation for a trait
    fn handle(&self);  // WARN: missing documentation for a method
}

Good

#![warn(missing_docs)]

//! User management module.

/// Represents a registered user in the system.
pub struct User {
    /// The user's display name.
    pub name: String,
    /// The user's age in years.
    pub age: u32,
}

/// Processes pending user requests.
///
/// # Examples
///
/// ```
/// process();
/// ```
pub fn process() { }

/// Handler trait for request processing.
pub trait Handler {
    /// Handle an incoming request.
    fn handle(&self);
}

Private Items

missing_docs only applies to pub items. Private items don't trigger warnings:

#![warn(missing_docs)]

struct Internal { }  // No warning - private

pub struct Public { }  // WARN - public, needs docs

Allow for Specific Items

#![warn(missing_docs)]

/// Documented module.
pub mod api {
    /// Documented struct.
    pub struct Config { }
    
    #[allow(missing_docs)]
    pub mod internal {
        // Internal API, docs not required
        pub struct Helper { }
    }
}

Gradual Adoption

For existing codebases, start with warn and fix incrementally:

// Phase 1: Warn, fix critical items
#![warn(missing_docs)]

// Phase 2: After cleanup, deny
#![deny(missing_docs)]

Combining with doc Attributes

#![warn(missing_docs)]
#![warn(rustdoc::broken_intra_doc_links)]
#![warn(rustdoc::private_intra_doc_links)]

Workspace Configuration

# In workspace Cargo.toml
[workspace.lints.rust]
missing_docs = "warn"

# Member crates inherit
[lints]
workspace = true

What to Document

Item	Doc Focus
Structs	Purpose, usage example
Struct fields	What it represents
Enums	When to use each variant
Functions	What it does, params, return
Traits	Contract and expectations
Modules	What the module provides

2.9 KiB Raw Blame History