Add new comment_within_doc lint

[GuillaumeGomez]

Fixes #15245.

Considering how many false positive we might trigger with this lint, I put it into pedantic.

cc @ojeda
r? @samueltardieu

changelog: Add new comment_within_doc lint

Summary Notes

• Feature-freeze by github-actions[bot]

Managed by @rustbot—see help for details

[rustbot]

Some changes occurred in clippy_lints/src/doc

cc @notriddle

[github-actions]

Lintcheck changes for 938e647

Lint	Added	Removed	Changed
clippy::comment_within_doc	3	0	0

This comment will be updated if you push new changes

[ojeda]

If I understand correctly, this finds surrounding cases like:

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

But at least #15245 was intended to only lint on empty ones like:

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

The reason was to be more conservative to avoid false positives -- at least in the Linux kernel we expect to be able to write comments together to docs, and we already have 6 adjacent cases we would hit, e.g. one of them:

/// Use the given initializer to in-place initialize a `T`.
///
/// If `T: !Unpin` it will not be able to move afterwards.
// We don't implement `InPlaceInit` because `ListArc` is implicitly pinned. This is similar to
// what we do for `Arc`.
#[inline]
pub fn pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self, E>

Moreover, I think we should also probably want to lint on adjacent cases, not just surrounded cases, e.g.

/// ...
//

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);
/// ```

[notriddle]

Not sure if this us supposed to be empty comments only, or if it's supposed to be any comment sandwiched between doc comment lines.

I'm not sure if blank-lines-only would have enough true positives to justify maintaining it. Has this happened more than once?

[notriddle]

That "fix" is wrong, isn't it?