New lint: Suggest using line doc comments for doc tests instead of doc block comments

What it does

This lint identifies the presence of a doc-test inside a doc block comment, and recommends using doc line comments instead.

This idea came about when I was running cargo test and to my surprise, my project had a doc-test which was ignored but suddenly became visible in the current beta toolchain (Enet4/dicom-rs#223). With this lint, one would have detected that the doc-test might not have been interpreted as such. If deemed sound, I can try to get some time to work on its implementation. I am not sure how well this would align with the component release cycle, since this lint is only useful if it can be combined with previous versions of the compiler.

Lint Name

doctest_in_block_comment

Category

suspicious

Advantage

Due to a regression in the compiler, leading * characters may be interpreted as being part of the actual comment text. This in turn makes doc-tests not be recognised as such, leading to ignored tests without any warning. By using doc line comments consistently, stumbling upon this regression is prevented entirely.

Drawbacks

This lint would be no longer needed once the compiler is patched (starting from version v1.60.0) and there is no interest within the project in supporting versions of the compiler with this regression.

Example

/** Foos a bar.
 *
 * # Example
 * ```
 * foo(5);
 * ```
 */
fn foo(bar: u32) {}

Could be written as:

/// Foos a bar.
///
/// # Example
/// ```
/// foo(5);
/// ```
fn foo(bar: u32) {}

Start by reviewing the proposed doctest_in_block_comment behavior and the cargo test scenario described in the issue, including the Rust examples. Done means the lint identifies doc-tests inside doc block comments and recommends equivalent doc line comments, while accounting for the stated compiler regression.