Add new lint `doc_overindented_list_items` #13711

ohno418 · 2024-11-20T08:48:44Z

Add a new lint doc_overindented_list_items to detect and fix list items
in docs that are overindented.

For example,

/// - first line
///      second line
fn foo() {}

this would be fixed to:

/// - first line
///   second line
fn foo() {}

This lint improves readabiliy and consistency in doc.

Followed lint naming conventions
Added passing UI tests (including committed .stderr file)
cargo test passes locally
Executed cargo dev update_lints
Added lint documentation
Run cargo dev fmt

changelog: [doc_overindented_list_items]: Added a new lint that detects overindented list items in docs
fixes: #13601

rustbot · 2024-11-20T08:48:50Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Centri3 (or someone else) some time within the next two weeks.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

@rustbot author: the review is finished, PR author should check the comments and take action accordingly
@rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

bors · 2024-12-03T16:09:14Z

☔ The latest upstream changes (presumably 19426bf) made this pull request unmergeable. Please resolve the merge conflicts.

Centri3

Implementation looks good to me, but I think it's best as a separate lint instead. As a separate lint it can still use the same code of course.

tests/ui/doc/doc_lazy_list.fixed

tests/ui/doc/doc_lazy_list.stderr

ohno418 · 2024-12-15T09:21:42Z

I think it's best as a separate lint instead.

Makes sense. I'll make a change.

Align bullet points and improve indentation in the `Invariants` section of the `GenDisk` struct documentation for better readability. [ Yutaro is also working on implementing the lint we suggested to catch this sort of issue in upstream Rust: rust-lang/rust-clippy#13601 rust-lang/rust-clippy#13711 Thanks a lot! - Miguel ] Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module") Signed-off-by: Yutaro Ohno <[email protected]> Reviewed-by: Boqun Feng <[email protected]> Acked-by: Andreas Hindborg <[email protected]> Link: https://lore.kernel.org/r/ZxkcU5yTFCagg_lX@ohnotp Signed-off-by: Miguel Ojeda <[email protected]>

ohno418 · 2024-12-23T11:27:00Z

@Centri3
Could you have another look at this?

@rustbot review

Centri3 · 2024-12-23T21:36:26Z

Just an initial comment: By "use the same code", I mean be in the same module :) Your original code is perfect in that regard, it just needs some refactoring to make it clear it's not just lazy continuation. Two lints can use the same code yet still emit different lints in both span_lint calls based on whatever condition necessary, See raw_strings.rs for an example of what I mean if our words aren't fully clear.

ohno418 · 2025-01-07T10:38:41Z

@Centri3
Thanks for your help, but I'm not quite sure I fully understand...
Does my change align with what you intended? Please have a look.

Centri3

Yeah this is about what I envisioned 👍

Centri3 · 2025-01-12T02:15:24Z

tests/ui/doc/doc_overindented_list_items.stderr

+help: remove unnecessary spaces
+   |
+LL | ///   this is overindented line too
+   |     ++


Just one thing: This suggestion is really silly. Rather than take-ing the expected indentation I think you should remove from the span instead as this might improve this suggestion

Oh, you're right. I'll make that change.

Centri3 · 2025-01-12T02:17:05Z

clippy_lints/src/doc/lazy_continuation.rs

Oh this could also be renamed but tbh I am not sure to what.. It's fine if it's kept as is

this could also be renamed

Hmm, indeed.

How about just "continuation.rs" (clippy_lints/src/doc/continuation.rs)? Since now this file handles false continuations. Would it be too general?

I'm not entirely sure it's a good name or not. I would agree to keep the filename as is.

ohno418 · 2025-01-27T08:08:05Z

@Centri3
I've modified stderr output. Could you have another look at this?

Centri3 · 2025-01-28T07:17:55Z

Dogfood failed:

 error: this `repeat().take()` can be written more concisely
   --> src/doc/lazy_continuation.rs:112:24
    |
112 |             let sugg = std::iter::repeat(" ").take(list_indentation).join("");
    |                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: consider using `repeat_n()` instead: `std::iter::repeat_n(" ", list_indentation)`
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#manual_repeat_n
    = note: `-D clippy::manual-repeat-n` implied by `-D clippy::all`
    = help: to override `-D clippy::all` add `#[allow(clippy::manual_repeat_n)]`

It passes locally because your branch is behind

Add a new lint `doc_overindented_list_items` to detect and fix list items in docs that are overindented. For example, ```rs /// - first line /// second line fn foo() {} ``` this would be fixed to: ```rs /// - first line /// second line fn foo() {} ``` This lint improves readabiliy and consistency in doc.

ohno418 · 2025-01-28T07:28:29Z

@Centri3
Oh, thanks. I've just rebased on the current master and fixed the error.

Aloso · 2025-01-31T21:18:13Z

I'm confused why this is implemented in clippy, instead of rustfmt. This whitespace is insignificant, and modifying insignificant whitespace for aesthetic reasons is rustfmt's job.

DJMcNab · 2025-02-05T08:30:27Z

clippy_lints/src/doc/mod.rs

+    /// ///   and this line is overindented.
+    /// # fn foo() {}
+    /// ```
+    #[clippy::version = "1.80.0"]


Is this accurate?

I'll take a look later, but I think it might be incorrect. I'll fix it in that case. Thanks!

I've just opened the PR: #14152

Starting with Rust 1.86.0 (to be released 2025-04-03), Clippy will have a new lint, `doc_overindented_list_items` [1], which catches cases of overindented list items. The lint has been added by Yutaro Ohno, based on feedback from the kernel [2] on a patch that fixed a similar case -- commit 0c5928d ("rust: block: fix formatting in GenDisk doc"). Clippy reports a few cases in the kernel, apart from the one already fixed in the commit above. One is this one: error: doc list item overindented --> rust/kernel/rbtree.rs:1152:5 | 1152 | /// null, it is a pointer to the root of the [`RBTree`]. | ^^^^ help: try using ` ` (2 spaces) | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_overindented_list_items = note: `-D clippy::doc-overindented-list-items` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::doc_overindented_list_items)]` Thus clean it up. Cc: Yutaro Ohno <[email protected]> Cc: [email protected] # Needed in 6.12.y and 6.13.y only (Rust is pinned in older LTSs). Fixes: a335e95 ("rust: rbtree: add `RBTree::entry`") Link: rust-lang/rust-clippy#13711 [1] Link: rust-lang/rust-clippy#13601 [2] Reviewed-by: Alice Ryhl <[email protected]> Reviewed-by: Yutaro Ohno <[email protected]> Link: https://lore.kernel.org/r/[email protected] [ There are a few other cases, so updated message. ] Signed-off-by: Miguel Ojeda <[email protected]>

Starting with Rust 1.86.0 (to be released 2025-04-03), Clippy will have a new lint, `doc_overindented_list_items` [1], which catches cases of overindented list items. The lint has been added by Yutaro Ohno, based on feedback from the kernel [2] on a patch that fixed a similar case -- commit 0c5928d ("rust: block: fix formatting in GenDisk doc"). Clippy reports a few cases in the kernel, apart from the one already fixed in the commit above. One is this one: error: doc list item overindented --> rust/kernel/rbtree.rs:1152:5 | 1152 | /// null, it is a pointer to the root of the [`RBTree`]. | ^^^^ help: try using ` ` (2 spaces) | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_overindented_list_items = note: `-D clippy::doc-overindented-list-items` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::doc_overindented_list_items)]` Thus clean it up. Cc: Yutaro Ohno <[email protected]> Cc: [email protected] # Needed in 6.12.y and 6.13.y only (Rust is pinned in older LTSs). Fixes: a335e95 ("rust: rbtree: add `RBTree::entry`") Link: rust-lang/rust-clippy#13711 [1] Link: rust-lang/rust-clippy#13601 [2] Reviewed-by: Alice Ryhl <[email protected]> Reviewed-by: Yutaro Ohno <[email protected]> Link: https://lore.kernel.org/r/[email protected] [ There are a few other cases, so updated message. - Miguel ] Signed-off-by: Miguel Ojeda <[email protected]>

Align bullet points and improve indentation in the `Invariants` section of the `GenDisk` struct documentation for better readability. [ Yutaro is also working on implementing the lint we suggested to catch this sort of issue in upstream Rust: rust-lang/rust-clippy#13601 rust-lang/rust-clippy#13711 Thanks a lot! - Miguel ] Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module") Signed-off-by: Yutaro Ohno <[email protected]> Reviewed-by: Boqun Feng <[email protected]> Acked-by: Andreas Hindborg <[email protected]> Link: https://lore.kernel.org/r/ZxkcU5yTFCagg_lX@ohnotp Signed-off-by: Miguel Ojeda <[email protected]>

commit 2e4f982 upstream. Starting with Rust 1.86.0 (to be released 2025-04-03), Clippy will have a new lint, `doc_overindented_list_items` [1], which catches cases of overindented list items. The lint has been added by Yutaro Ohno, based on feedback from the kernel [2] on a patch that fixed a similar case -- commit 0c5928d ("rust: block: fix formatting in GenDisk doc"). Clippy reports a few cases in the kernel, apart from the one already fixed in the commit above. One is this one: error: doc list item overindented --> rust/kernel/rbtree.rs:1152:5 | 1152 | /// null, it is a pointer to the root of the [`RBTree`]. | ^^^^ help: try using ` ` (2 spaces) | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_overindented_list_items = note: `-D clippy::doc-overindented-list-items` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::doc_overindented_list_items)]` Thus clean it up. Cc: Yutaro Ohno <[email protected]> Cc: [email protected] # Needed in 6.12.y and 6.13.y only (Rust is pinned in older LTSs). Fixes: a335e95 ("rust: rbtree: add `RBTree::entry`") Link: rust-lang/rust-clippy#13711 [1] Link: rust-lang/rust-clippy#13601 [2] Reviewed-by: Alice Ryhl <[email protected]> Reviewed-by: Yutaro Ohno <[email protected]> Link: https://lore.kernel.org/r/[email protected] [ There are a few other cases, so updated message. - Miguel ] Signed-off-by: Miguel Ojeda <[email protected]> Signed-off-by: Greg Kroah-Hartman <[email protected]>

Align bullet points and improve indentation in the `Invariants` section of the `GenDisk` struct documentation for better readability. [ Yutaro is also working on implementing the lint we suggested to catch this sort of issue in upstream Rust: rust-lang/rust-clippy#13601 rust-lang/rust-clippy#13711 Thanks a lot! - Miguel ] Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module") Signed-off-by: Yutaro Ohno <[email protected]> Reviewed-by: Boqun Feng <[email protected]> Acked-by: Andreas Hindborg <[email protected]> Link: https://lore.kernel.org/r/ZxkcU5yTFCagg_lX@ohnotp Signed-off-by: Miguel Ojeda <[email protected]>

commit 0c5928d upstream. Align bullet points and improve indentation in the `Invariants` section of the `GenDisk` struct documentation for better readability. [ Yutaro is also working on implementing the lint we suggested to catch this sort of issue in upstream Rust: rust-lang/rust-clippy#13601 rust-lang/rust-clippy#13711 Thanks a lot! - Miguel ] Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module") Signed-off-by: Yutaro Ohno <[email protected]> Reviewed-by: Boqun Feng <[email protected]> Acked-by: Andreas Hindborg <[email protected]> Link: https://lore.kernel.org/r/ZxkcU5yTFCagg_lX@ohnotp Signed-off-by: Miguel Ojeda <[email protected]> Signed-off-by: Greg Kroah-Hartman <[email protected]>

Starting with Rust 1.86.0 (to be released 2025-04-03), Clippy will have a new lint, `doc_overindented_list_items` [1], which catches cases of overindented list items. The lint has been added by Yutaro Ohno, based on feedback from the kernel [2] on a patch that fixed a similar case -- commit 0c5928d ("rust: block: fix formatting in GenDisk doc"). Clippy reports a few cases in the kernel, apart from the one already fixed in the commit above. One is this one: error: doc list item overindented --> rust/kernel/rbtree.rs:1152:5 | 1152 | /// null, it is a pointer to the root of the [`RBTree`]. | ^^^^ help: try using ` ` (2 spaces) | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_overindented_list_items = note: `-D clippy::doc-overindented-list-items` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::doc_overindented_list_items)]` Thus clean it up. Cc: Yutaro Ohno <[email protected]> Cc: [email protected] # Needed in 6.12.y and 6.13.y only (Rust is pinned in older LTSs). Fixes: a335e95 ("rust: rbtree: add `RBTree::entry`") Link: rust-lang/rust-clippy#13711 [1] Link: rust-lang/rust-clippy#13601 [2] Reviewed-by: Alice Ryhl <[email protected]> Reviewed-by: Yutaro Ohno <[email protected]> Link: https://lore.kernel.org/r/[email protected] [ There are a few other cases, so updated message. - Miguel ] Signed-off-by: Miguel Ojeda <[email protected]>

commit 2e4f982 upstream. Starting with Rust 1.86.0 (to be released 2025-04-03), Clippy will have a new lint, `doc_overindented_list_items` [1], which catches cases of overindented list items. The lint has been added by Yutaro Ohno, based on feedback from the kernel [2] on a patch that fixed a similar case -- commit 0c5928d ("rust: block: fix formatting in GenDisk doc"). Clippy reports a few cases in the kernel, apart from the one already fixed in the commit above. One is this one: error: doc list item overindented --> rust/kernel/rbtree.rs:1152:5 | 1152 | /// null, it is a pointer to the root of the [`RBTree`]. | ^^^^ help: try using ` ` (2 spaces) | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_overindented_list_items = note: `-D clippy::doc-overindented-list-items` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::doc_overindented_list_items)]` Thus clean it up. Cc: Yutaro Ohno <[email protected]> Cc: [email protected] # Needed in 6.12.y and 6.13.y only (Rust is pinned in older LTSs). Fixes: a335e95 ("rust: rbtree: add `RBTree::entry`") Link: rust-lang/rust-clippy#13711 [1] Link: rust-lang/rust-clippy#13601 [2] Reviewed-by: Alice Ryhl <[email protected]> Reviewed-by: Yutaro Ohno <[email protected]> Link: https://lore.kernel.org/r/[email protected] [ There are a few other cases, so updated message. - Miguel ] Signed-off-by: Miguel Ojeda <[email protected]> Signed-off-by: Greg Kroah-Hartman <[email protected]> (cherry picked from commit 05b9d614eb64bcd1c590b07698be72d43f51efaf) Signed-off-by: Jack Vogel <[email protected]>

commit 0c5928d upstream. Align bullet points and improve indentation in the `Invariants` section of the `GenDisk` struct documentation for better readability. [ Yutaro is also working on implementing the lint we suggested to catch this sort of issue in upstream Rust: rust-lang/rust-clippy#13601 rust-lang/rust-clippy#13711 Thanks a lot! - Miguel ] Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module") Signed-off-by: Yutaro Ohno <[email protected]> Reviewed-by: Boqun Feng <[email protected]> Acked-by: Andreas Hindborg <[email protected]> Link: https://lore.kernel.org/r/ZxkcU5yTFCagg_lX@ohnotp Signed-off-by: Miguel Ojeda <[email protected]> Signed-off-by: Greg Kroah-Hartman <[email protected]> (cherry picked from commit 2f8e609aea9a0deb43a22ae738258abab392cbbc) Signed-off-by: Jack Vogel <[email protected]>

rustbot assigned Centri3 Nov 20, 2024

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties label Nov 20, 2024

Centri3 reviewed Dec 14, 2024

View reviewed changes

tests/ui/doc/doc_lazy_list.fixed Outdated Show resolved Hide resolved

tests/ui/doc/doc_lazy_list.stderr Outdated Show resolved Hide resolved

ojeda mentioned this pull request Dec 17, 2024

Clippy wanted features & bugfixes Rust-for-Linux/linux#349

Open

46 tasks

ohno418 force-pushed the doc-overindented-list-item branch 3 times, most recently from d518346 to f33f47d Compare December 23, 2024 11:18

ohno418 changed the title ~~Add lint for overindented list items in docs~~ Add new lint doc_overindented_list_items Dec 23, 2024

ohno418 requested a review from Centri3 December 23, 2024 11:30

ohno418 force-pushed the doc-overindented-list-item branch from f33f47d to c258296 Compare January 7, 2025 10:28

Centri3 reviewed Jan 12, 2025

View reviewed changes

ohno418 force-pushed the doc-overindented-list-item branch from c258296 to ba5a160 Compare January 14, 2025 08:07

ohno418 requested a review from Centri3 January 14, 2025 08:08

Centri3 approved these changes Jan 28, 2025

View reviewed changes

Centri3 added this pull request to the merge queue Jan 28, 2025

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Jan 28, 2025

ohno418 force-pushed the doc-overindented-list-item branch from ba5a160 to 4693d0a Compare January 28, 2025 07:24

Centri3 added this pull request to the merge queue Jan 28, 2025

Merged via the queue into rust-lang:master with commit 80c2d09 Jan 28, 2025
11 checks passed

ohno418 deleted the doc-overindented-list-item branch January 28, 2025 09:09

alex-semenyuk mentioned this pull request Feb 2, 2025

Update version for doc_include_without_cfg #14138

Closed

DJMcNab reviewed Feb 5, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add new lint `doc_overindented_list_items` #13711

Add new lint `doc_overindented_list_items` #13711

ohno418 commented Nov 20, 2024 •

edited

Loading

rustbot commented Nov 20, 2024

bors commented Dec 3, 2024

Centri3 left a comment

ohno418 commented Dec 15, 2024

ohno418 commented Dec 23, 2024

Centri3 commented Dec 23, 2024 •

edited

Loading

ohno418 commented Jan 7, 2025 •

edited

Loading

Centri3 left a comment

Centri3 Jan 12, 2025

ohno418 Jan 13, 2025

ohno418 Jan 14, 2025

Centri3 Jan 12, 2025

ohno418 Jan 14, 2025

ohno418 commented Jan 27, 2025

Centri3 commented Jan 28, 2025 •

edited

Loading

ohno418 commented Jan 28, 2025

Aloso commented Jan 31, 2025

DJMcNab Feb 5, 2025

ohno418 Feb 5, 2025

ohno418 Feb 5, 2025

Add new lint doc_overindented_list_items #13711

Add new lint doc_overindented_list_items #13711

Conversation

ohno418 commented Nov 20, 2024 • edited Loading

rustbot commented Nov 20, 2024

bors commented Dec 3, 2024

Centri3 left a comment

Choose a reason for hiding this comment

ohno418 commented Dec 15, 2024

ohno418 commented Dec 23, 2024

Centri3 commented Dec 23, 2024 • edited Loading

ohno418 commented Jan 7, 2025 • edited Loading

Centri3 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ohno418 commented Jan 27, 2025

Centri3 commented Jan 28, 2025 • edited Loading

ohno418 commented Jan 28, 2025

Aloso commented Jan 31, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Add new lint `doc_overindented_list_items` #13711

Add new lint `doc_overindented_list_items` #13711

ohno418 commented Nov 20, 2024 •

edited

Loading

Centri3 commented Dec 23, 2024 •

edited

Loading

ohno418 commented Jan 7, 2025 •

edited

Loading

Centri3 commented Jan 28, 2025 •

edited

Loading