RS.CLIPPY.SUSPICIOUS_DOC_COMMENTS

Suspicious usage of (outer) doc comments

This checker is a Clippy lint created by The Rust Project Contributors. The documentation shown here is a copy of the original documentation for: suspicious_doc_comments. Copyright ©2025 The Rust Team. All rights reserved.

What it does

Detects the use of outer doc comments (///, /**) followed by a bang (!): ///!

Why is this bad?

Triple-slash comments (known as "outer doc comments") apply to items that follow it. An outer doc comment followed by a bang (i.e. ///!) has no specific meaning.

The user most likely meant to write an inner doc comment (//!, /*!), which applies to the parent item (i.e. the item that the comment is contained in, usually a module or crate).

Known problems

Inner doc comments can only appear before items, so there are certain cases where the suggestion made by this lint is not valid code. For example:

fn foo() {}
///!
fn bar() {}

This lint detects the doc comment and suggests changing it to //!, but an inner doc comment is not valid at that position.

Example

In this example, the doc comment is attached to the function, rather than the module.

pub mod util {
    ///! This module contains utility functions.

    pub fn dummy() {}
}

Use instead:

pub mod util {
    //! This module contains utility functions.

    pub fn dummy() {}
}