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.

Sign up for GitHub

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

Jump to bottom

Add new lint doc_overindented_list_items #13711

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add new lint doc_overindented_list_items #13711

wants to merge 1 commit into from
+219 −52

Conversation

ohno418
Copy link

@ohno418 ohno418 commented Nov 20, 2024 •
edited
Loading

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
Copy link
Collaborator

rustbot commented Nov 20, 2024

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

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

bors commented Dec 3, 2024

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

Centri3
Centri3 reviewed Dec 14, 2024
View reviewed changes
Copy link
Member

@Centri3 Centri3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Outdated Show resolved Hide resolved
tests/ui/doc/doc_lazy_list.stderr Outdated Show resolved Hide resolved
@ohno418
Copy link
Author

ohno418 commented Dec 15, 2024

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

Makes sense. I'll make a change.

@ojeda ojeda mentioned this pull request Dec 17, 2024
Open
33 tasks
ojeda pushed a commit to Rust-for-Linux/linux that referenced this pull request Dec 18, 2024
@ohno418 @ojeda
rust: block: fix formatting in GenDisk doc
0c5928d 
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 ohno418 force-pushed the doc-overindented-list-item branch 3 times, most recently from d518346 to f33f47d Compare December 23, 2024 11:18
@ohno418 ohno418 changed the title Add lint for overindented list items in docs Add new lint doc_overindented_list_items Dec 23, 2024
@ohno418
Copy link
Author

ohno418 commented Dec 23, 2024

@Centri3
Could you have another look at this?

@rustbot review

@ohno418 ohno418 requested a review from Centri3 December 23, 2024 11:30
@Centri3
Copy link
Member

Centri3 commented Dec 23, 2024 •
edited
Loading

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 ohno418 force-pushed the doc-overindented-list-item branch from f33f47d to c258296 Compare January 7, 2025 10:28
@ohno418
Copy link
Author

ohno418 commented Jan 7, 2025 •
edited
Loading

@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
Centri3 reviewed Jan 12, 2025
View reviewed changes
Copy link
Member

@Centri3 Centri3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah this is about what I envisioned 👍

tests/ui/doc/doc_overindented_list_items.stderr Outdated
help: remove unnecessary spaces
|
LL | /// this is overindented line too
| ++
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Centri3
Centri3 reviewed Jan 12, 2025
View reviewed changes
clippy_lints/src/doc/lazy_continuation.rs Outdated
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Add new lint doc_overindented_list_items
ba5a160 
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 ohno418 force-pushed the doc-overindented-list-item branch from c258296 to ba5a160 Compare January 14, 2025 08:07
@ohno418 ohno418 requested a review from Centri3 January 14, 2025 08:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Centri3 Centri3 Awaiting requested review from Centri3

Assignees

@Centri3 Centri3

Labels
S-waiting-on-review Status: Awaiting review from the assignee but also interested parties
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Overindented lines lint (similar to doc_lazy_continuation)
4 participants
@ohno418 @rustbot @bors @Centri3