Documentation mistakenly using `///` instead of `//!`

[ojeda]

What it does

In the Linux kernel we had some documentation added with /// instead of //!, which meant the docs applied to a use line and thus silently discarded.

Advantage

Documentation is not discarded silently.

Drawbacks

False positives when someone does want to document an item that follows. However, if it is something like a private use, it is likely it was a mistake. Thus the lint should limit itself to such cases.

Example

Both

//! Title.
/// Long...
///
/// ...description.
use ...;

and

//! Title.

/// Long...
///
/// ...description.
use ...;

should probably have been written as

//! Title.
//!
//! Long...
//!
//! ...description.

use ...;

[ojeda]

@rustbot label +A-documentation

[ojeda]

I suspect A-documentation is meant for Clippy's documentation, rather than lints related to issues with the user documentation, i.e. what is processed by rustdoc in their code.

Should I use another one for this sort of issue? Should I @ someone from rustdoc for this sort of lint e.g. @GuillaumeGomez?

Thanks!

@rustbot label -A-documentation

[GuillaumeGomez]

Ah interesting. For use items when there is no items before them, it definitely sounds like something that should be linted. But being part of clippy instead of rustdoc is the right call imo.