clippy::missing_panics_doc: Checks the doc comments of publicly visible functions that may panic and warns if there is no # Panics section

/// # Panics
///
/// Will panic if y is 0
pub fn divide_by(x: i32, y: i32) -> i32 {
    if y == 0 {
        panic!("Cannot divide by 0")
    } else {
        x / y
    }
}

pub fn will_not_panic(x: usize) {
    #[expect(clippy::missing_panics_doc, reason = "infallible")]
    let y = NonZeroUsize::new(1).unwrap();

    // If any panics are added in the future the lint will still catch them
}

[lints.clippy]
missing_panics_doc = "warn"

#![warn(clippy::missing_panics_doc)]

cargo clippy -- -W clippy::missing-panics-doc

Clippy's own documentation

What it does

Checks the doc comments of publicly visible functions that may panic and warns if there is no # Panics section.

Why is this bad?

Documenting the scenarios in which panicking occurs can help callers who do not want to panic to avoid those situations.

Examples

Since the following function may panic it has a # Panics section in its doc comment:

/// # Panics
///
/// Will panic if y is 0
pub fn divide_by(x: i32, y: i32) -> i32 {
    if y == 0 {
        panic!("Cannot divide by 0")
    } else {
        x / y
    }
}

Individual panics within a function can be ignored with #[expect] or #[allow]:

pub fn will_not_panic(x: usize) {
    #[expect(clippy::missing_panics_doc, reason = "infallible")]
    let y = NonZeroUsize::new(1).unwrap();

    // If any panics are added in the future the lint will still catch them
}

Configuration

• check-private-items: Whether to also run the listed lints on private items.

  (default: false)

From the Clippy lint list (0.1.99), part of the Rust project, MIT or Apache-2.0. Official entry.

Related lints

• too_many_linesChecks for functions with a large amount of lines
• missing_errors_docChecks the doc comments of publicly visible functions that return a Result type and warns if there is no # Errors section
• must_use_candidateChecks for public functions that have no #[must_use] attribute, but return something not already marked must-use, have no mutable arg and mutate no statics
• mismatching_type_param_order`Foo` has a similarly named generic type parameter `B` in its declaration, but in a different order
• missing_fields_in_debugmanual `Debug` impl does not include all fields
• mut_mutmultiple successive mutable borrows
• naive_bytecountChecks for naive byte counts

All 847 Clippy lints · Rust compiler errors · Cargo.toml checker