rust-clippy icon indicating copy to clipboard operation
rust-clippy copied to clipboard

`too_long_first_doc_paragraph` only considers markdown source not the rendered output

Open Freax13 opened this issue 1 year ago • 1 comments

Summary

too_long_first_doc_paragraph doesn't take into account that the length of the markdown source is not necessarily the length of the rendered output e.g. the raw markdown for the link [foo](barbaz) contains 13 bytes, but the rendered output is only 3 bytes. This leads to warnings about short paragraphs with long links.

Lint Name

too_long_first_doc_paragraph

Reproducer

I tried this code:

/// This doc comment contains two references: [this](https://fooooooooooooooooooooooooooooooooooooooooooooooooooooooooo.com)
/// and [this](https://fooooooooooooooooooooooooooooooooooooooooooooooooooooooooo.com)
pub fn foo() {}

I saw this happen:

warning: first doc comment paragraph is too long
 --> src/lib.rs:1:1
  |
1 | / /// This doc comment contains two references: [this](https://fooooooooooooooooooooooooooooooooooooooooooooooooooooooooo.com)
2 | | /// and [this](https://fooooooooooooooooooooooooooooooooooooooooooooooooooooooooo.com)
  | |_
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#too_long_first_doc_paragraph
  = note: `#[warn(clippy::too_long_first_doc_paragraph)]` on by default

I expected to see this happen: No warning

Version

rustc 1.82.0-nightly (1f12b9b0f 2024-08-27)
binary: rustc
commit-hash: 1f12b9b0fdbe735968ac002792a720f0ba4faca6
commit-date: 2024-08-27
host: x86_64-unknown-linux-gnu
release: 1.82.0-nightly
LLVM version: 19.1.0

Additional Labels

No response

Freax13 avatar Aug 28 '24 10:08 Freax13

I wonder if we should demote this to a nursery lint until then?

Thought: Without parsing every line as markdown, we can save some performance by only running this check on code we plan to lint on.

Manishearth avatar Oct 11 '24 19:10 Manishearth