What it does

Sometimes a slash may be missed within (or adjacent to) a larger comment, which can affect rendering of the docs.

The lint should lint when there is an empty comment (//) within docs (///, //!). Note that it should not lint in cases where there is actually something written, e.g. a // TODO: in the middle of docs. It should not lint either if there is any non-empty comment line in the same group of comment lines.

This happened in a patch to the Linux kernel: https://lore.kernel.org/rust-for-linux/CANiq72nh71s9to5v1KHJWN79bEFv97zN6jcGJyEQkaJZ5UuJfg@mail.gmail.com/.

Cc: rustdoc @GuillaumeGomez since this is one of those documentation-related ones.

Advantage

No response

Drawbacks

No response

Example

/// ...
//
/// ...

could be written as:

/// ...
///
/// ...

Similarly, empty comments at the beginning or end of docs should also be linted:

//
/// ...

/// ...
//

The lint should not trigger if there is content in the comment, however:

/// ...
// ...
/// ...

The lint should not trigger if there is content in another line in the same group of consecutive // lines:

/// ...
//
// ...

On a possible extension that lints on non-empty comments

From #15260 (comment):

So I think there are these cases:

• Surrounding, empty in all lines.
• Surrounding, with some content in at least one line.
• Adjacent, empty in all lines.
• Adjacent, with some content in at least one line.

Of those, 1 and 3 seem both pretty safe to enable and that was my original intention with the issue.

4 is not something we would want at least for the Linux kernel, since we expect to write those (and we have 6 cases already).

And finally 3 could perhaps be interesting for some projects -- in the Linux kernel we don't have any case yet (if I grepped correctly), but when I wrote our coding guidelines about comments I expected it to be possible (https://docs.kernel.org/rust/coding-guidelines.html#comments):

/// # Examples
///
// TODO: Find a better example.
/// ```
/// let foo = f(42);
/// ```