Suspicious comment (//) adjacent to doc comment (///)

What it does

If a // comment is found adjacent to a doc comment, warn, as it may have been intended to be part of the doc comment.

Some cases that definitely should be warned about:

• a // comment above a /// doc comment empty line
• a // comment (either single or multi-line) surrounded by doc comment lines

Some edge cases:

• a // comment before a doc comment
• a `// comment after a doc comment

Some cases that should definitely be excluded:

• comments beginning with an all-caps word, like TODO, FIXME, PERF
• comments defined by /* */, as that is much harder to typo

Lint Name

suspicious-comment-beside-doc-comment

Category

suspicious

Advantage

Ordinary comments do not appear in generated documentation.

Drawbacks

1. It becomes harder to comment on the documentation itself. This is a pretty rare pattern; usually I'd use issue trackers for that sort of thing.
2. The exact rule should be tuned to make sure that doc comments on a struct / function can exist beside ordinary comments without triggering false positives.

Example

    // Consumes the [`OwningPtr`] to obtain ownership of the underlying data of type `T`.
    ///
    /// # Safety
    /// Must point to a valid `T`.

Was likely intended to be

    /// Consumes the [`OwningPtr`] to obtain ownership of the underlying data of type `T`.
    ///
    /// # Safety
    /// Must point to a valid `T`.

No implementation files or tests are identified in the issue. Start by locating Clippy's existing suspicious-comment lints and their tests, then define the adjacency cases and exclusions described here; done means the new lint warns on the specified // and /// patterns without flagging uppercase marker comments or /* */ comments.