Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

too_long_first_doc_paragraph only considers markdown source not the rendered output #13315

Open
Freax13 opened this issue Aug 28, 2024 · 1 comment
Labels
C-bug Category: Clippy is not doing the correct thing I-false-positive Issue: The lint was triggered on code it shouldn't have

Comments

@Freax13
Copy link

Freax13 commented Aug 28, 2024

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 Freax13 added C-bug Category: Clippy is not doing the correct thing I-false-positive Issue: The lint was triggered on code it shouldn't have labels Aug 28, 2024
taiki-e pushed a commit to rust-lang/futures-rs that referenced this issue Sep 14, 2024
* Fix unexpected `cfg` condition name: ... warnings introduced in Rust 1.80

See https://blog.rust-lang.org/2024/05/06/check-cfg.html

* io_slice_advance feature is now stable

* clippy: enable missing_const_for_thread_local lint, now checks for MSRV (see rust-lang/rust-clippy#12404)

* clippy: fixes for "doc list item without indentation" lint

* clippy: ignore incorrect "first doc comment paragraph is too long" warning

see rust-lang/rust-clippy#13315

* clippy: allow long first paragraphs in select... fn doc comments

* use workspace level setting to ignore error about the futures_sanitizer unexpected config
taiki-e pushed a commit to rust-lang/futures-rs that referenced this issue Oct 5, 2024
* Fix unexpected `cfg` condition name: ... warnings introduced in Rust 1.80

See https://blog.rust-lang.org/2024/05/06/check-cfg.html

* io_slice_advance feature is now stable

* clippy: enable missing_const_for_thread_local lint, now checks for MSRV (see rust-lang/rust-clippy#12404)

* clippy: fixes for "doc list item without indentation" lint

* clippy: ignore incorrect "first doc comment paragraph is too long" warning

see rust-lang/rust-clippy#13315

* clippy: allow long first paragraphs in select... fn doc comments

* use workspace level setting to ignore error about the futures_sanitizer unexpected config
taiki-e pushed a commit to rust-lang/futures-rs that referenced this issue Oct 5, 2024
* Fix unexpected `cfg` condition name: ... warnings introduced in Rust 1.80

See https://blog.rust-lang.org/2024/05/06/check-cfg.html

* io_slice_advance feature is now stable

* clippy: enable missing_const_for_thread_local lint, now checks for MSRV (see rust-lang/rust-clippy#12404)

* clippy: fixes for "doc list item without indentation" lint

* clippy: ignore incorrect "first doc comment paragraph is too long" warning

see rust-lang/rust-clippy#13315

* clippy: allow long first paragraphs in select... fn doc comments

* use workspace level setting to ignore error about the futures_sanitizer unexpected config
taiki-e pushed a commit to rust-lang/futures-rs that referenced this issue Oct 5, 2024
* Fix unexpected `cfg` condition name: ... warnings introduced in Rust 1.80

See https://blog.rust-lang.org/2024/05/06/check-cfg.html

* io_slice_advance feature is now stable

* clippy: enable missing_const_for_thread_local lint, now checks for MSRV (see rust-lang/rust-clippy#12404)

* clippy: fixes for "doc list item without indentation" lint

* clippy: ignore incorrect "first doc comment paragraph is too long" warning

see rust-lang/rust-clippy#13315

* clippy: allow long first paragraphs in select... fn doc comments

* use workspace level setting to ignore error about the futures_sanitizer unexpected config
@Manishearth
Copy link
Member

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.

k9withabone added a commit to k9withabone/compose_spec_rs that referenced this issue Oct 18, 2024
Allowed `clippy::too_long_first_doc_paragraph` on
`compose_spec::Extensions` due to false positive, see
rust-lang/rust-clippy#13315.

Allowed `clippy::result_large_err` on `into_short()` methods as they are
returning ownership on error and are not expected to be bubbled up
directly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C-bug Category: Clippy is not doing the correct thing I-false-positive Issue: The lint was triggered on code it shouldn't have
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants