Clippy lints / Suspicious
Clippy lint · Suspicious · checked with Clippy 0.1.99
clippy::suspicious_doc_comments: this is an outer doc comment and does not apply to the parent module or crate
What it meansDetects the use of outer doc comments (///, /**) followed by a bang (!): ///! It is in the suspicious group and warns by default.
What you see
warning: this is an outer doc comment and does not apply to the parent module or crate --> main.rs:4:1 | 4 | ///! | ^^^^ | = help: for further information visit https://rust-lang.github.io/rust-clippy/stable/index.html#suspicious_doc_comments = note: `#[warn(clippy::suspicious_doc_comments)]` on by default help: use an inner doc comment to document the parent module or crate | 4 - ///! 4 + //! |
Real output of Clippy 0.1.99 (Rust 1.99) on the example below. Names and line numbers in yours will differ.
Does it matter?
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).
Code that is most likely wrong or useless. Warns by default.
How to fix it
Clippy does not fix this one automatically (its suggestion may change behaviour, so it only shows it). Change the code by hand:
Flagged
fn foo() {}
///!
fn bar() {}
Write this instead
pub mod util {
///! This module contains utility functions.
pub fn dummy() {}
}
Turn it off, or on
Allow it where it does not fit your code, as narrowly as you can:
On one item
#[allow(clippy::suspicious_doc_comments)]
fn my_function() { /* ... */ }Whole crate (Cargo.toml)
[lints.clippy]
suspicious_doc_comments = "allow"One run
cargo clippy -- -A clippy::suspicious-doc-commentsThe [lints] table needs Rust 1.74 or newer. In a workspace, put it under [workspace.lints.clippy] and add [lints] workspace = true to each member.
Clippy's own documentation
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() {}
}
From the Clippy lint list (0.1.99), part of the Rust project, MIT or Apache-2.0. Official entry.
Related lints
- suspicious_arithmetic_implLints for suspicious operations in impls of arithmetic operators, e.g. subtracting elements in an Add impl
- suspicious_assignment_formattingthis looks like you are trying to use `.. -= ..`, but you really are doing `.. = (- ..)`
- suspicious_command_arg_spacesingle argument that looks like it should be multiple arguments
- suspicious_else_formattingthis is an `else {..}` but the formatting might hide it
- suspicious_mapthis call to `map()` won't have an effect on the call to `count()`
- suspicious_op_assign_implLints for suspicious operations in impls of OpAssign, e.g. subtracting elements in an AddAssign impl
All 847 Clippy lints · Rust compiler errors · Cargo.toml checker
Up next
Related lintclippy::suspicious_arithmetic_implLints for suspicious operations in impls of arithmetic operators, e.g. subtracting elements in an Add implRead it next →Did this answer your question?