Seemingly false positive of doc_lazy_continuation

[torokati44]

Summary

We started getting these lints here: https://github.com/ruffle-rs/ruffle/actions/runs/9463299965/job/26068182584#step:6:1150

The actual piece of code: https://github.com/ruffle-rs/ruffle/blob/2b17b6ce20591b958b879e27182ad5d0c5712084/core/src/avm2/globals/flash/display/graphics.rs#L416-L482

Instinctively I don't see anything wrong with it, and it looks like the /// and // blocks, separated by empty lines, are conflated in various ways by different tools.

Lint Name

doc_lazy_continuation

Reproducer

I tried this code:

/// This is a constant.
///
/// The meaning of which should not be explained.
const A: i32 = 42;

/// This is another constant, no longer used.
///
/// This block of documentation has a long
/// explanation and derivation to explain
/// why it is what it is, and how it's used.
///
/// It is left here for historical reasons, and
/// for reference.
///
/// Reasons it's great:
///  - First reason
///  - Second reason
//const B: i32 = 1337;

/// This is yet another constant.
///
/// This has a similar fate as `B`.
///
/// Reasons it's useful:
///  1. First reason
///  2. Second reason
//const C: i32 = 8008;

/// This is still in use.
const D: i32 = 20;

I saw this happen:

warning: doc list item missing indentation
  --> src/lib.rs:21:5
   |
21 | /// This is yet another constant.
   |     ^
   |
   = help: if this is supposed to be its own paragraph, add a blank line
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
   = note: `#[warn(clippy::doc_lazy_continuation)]` on by default
help: indent this line
   |
21 | ///    This is yet another constant.
   |     +++

warning: doc list item missing indentation
  --> src/lib.rs:30:5
   |
30 | /// This is still in use.
   |     ^
   |
   = help: if this is supposed to be its own paragraph, add a blank line
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_lazy_continuation
help: indent this line
   |
30 | ///     This is still in use.
   |     ++++

I expected to see this happen:

Somehow these warnings don't seem right when looking at the code snippet with human eyes.

Version

$ cargo +beta -vV
cargo 1.80.0-beta.1 (34a6a87d8 2024-06-04)
release: 1.80.0-beta.1
commit-hash: 34a6a87d8a2330d8c9d578f927489689328a652d
commit-date: 2024-06-04
host: x86_64-unknown-linux-gnu
libgit2: 1.7.2 (sys:0.18.3 vendored)
libcurl: 8.6.0-DEV (sys:0.4.72+curl-8.6.0 vendored ssl:OpenSSL/1.1.1w)
ssl: OpenSSL 1.1.1w  11 Sep 2023
os: Fedora 40.0.0 [64-bit]

Additional Labels

No response

[Alexendoo]

What's happening here is doc comments are converted to #[doc = "..."] attributes so rustdoc essentially sees

/// This is a constant.
///
/// The meaning of which should not be explained.
const A: i32 = 42;

/// This is another constant, no longer used.
///
/// This block of documentation has a long
/// explanation and derivation to explain
/// why it is what it is, and how it's used.
///
/// It is left here for historical reasons, and
/// for reference.
///
/// Reasons it's great:
///  - First reason
///  - Second reason
/// This is yet another constant.
///
/// This has a similar fate as `B`.
///
/// Reasons it's useful:
///  1. First reason
///  2. Second reason
/// This is still in use.
const D: i32 = 20;

But the output is confusing, we should probably have a lint for this behaviour since it's unexpected and suppress the other doc lints when it triggers

[torokati44]

suppress the other doc lints when it triggers

That would be at the cost of occasional false negatives, right?

[Alexendoo]

If we make it so that they're only suppressed when the lint is actually shown we should be good, that way you receive the other lints again after either fixing or #[allow]ing it

[workingjubilee]

False negatives are massively preferable to false positives. Clippy has 433 false-positive issues open and only 72 false-negatives about now. It should be the other way around.

[Alexendoo]

Few false negatives are reported because they're hard to notice and/or just considered part of the territory of a linter, that is despite there being an essentially never ending amount of them. But why comment that here? Obviously we know false positives are not good