Skip to content

Docs normalization#18831

Merged
AlexWaygood merged 29 commits intoastral-sh:mainfrom
MeGaGiGaGon:docs-normalization
Jun 20, 2025
Merged

Docs normalization#18831
AlexWaygood merged 29 commits intoastral-sh:mainfrom
MeGaGiGaGon:docs-normalization

Conversation

@MeGaGiGaGon
Copy link
Contributor

@MeGaGiGaGon MeGaGiGaGon commented Jun 20, 2025

Summary

While working on a detector for #15584, I noticed several inconsistencies in the docs, so this PR fixes them.

  • Blank line between doc comment and #[derive(ViolationMetadata)]
  • Empty doc comment before #[derive(ViolationMetadata)]
  • ## Fix Safety instead of ## Fix safety

Test Plan

N/A, no functionality/tests affected

MeGaGiGaGon added 25 commits June 20, 2025 11:29
@MeGaGiGaGon
Update custom_type_var_for_self.rs
e8131a6
@MeGaGiGaGon
Update replace_str_enum.rs
cd5edfc
@MeGaGiGaGon
Update whitespace_after_decorator.rs
d5f92d5
@MeGaGiGaGon
Update dict_index_missing_items.rs
73397e0
@MeGaGiGaGon
Update missing_maxsplit_arg.rs
4dc704a
@MeGaGiGaGon
Update redefined_argument_from_local.rs
af00205
@MeGaGiGaGon
Update fastapi_redundant_response_model.rs
540ecbf
@MeGaGiGaGon
Update assertion.rs
d6ffde5
@MeGaGiGaGon
Update implicit_cwd.rs
e698d8b
@MeGaGiGaGon
Update duplicate_class_field_definition.rs
723ad39
@MeGaGiGaGon
Update function.rs
d1a0205
@MeGaGiGaGon
Update trailing_whitespace.rs
70740b3
@MeGaGiGaGon
Update trailing_whitespace.rs
d68e6c3
@MeGaGiGaGon
Update decimal_from_float_literal.rs
3dd5b09
@MeGaGiGaGon
Update builtin_import_shadowing.rs
b5d8253
@MeGaGiGaGon
Update function.rs
2aaf7de
@MeGaGiGaGon
Update ambiguous_variable_name.rs
bce75f4
@MeGaGiGaGon
Update nan_comparison.rs
7a97fa3
@MeGaGiGaGon
Update redeclared_assigned_name.rs
0f049c6
@MeGaGiGaGon
Update unnecessary_dunder_call.rs
49718c1
@MeGaGiGaGon
Update regex_flag_alias.rs
8020a96
@MeGaGiGaGon
Update invalid_formatter_suppression_comment.rs
65c085f
@MeGaGiGaGon
Update unnecessary_round.rs
7009cac
@MeGaGiGaGon
Update custom_type_var_for_self.rs
3050087
@MeGaGiGaGon
Update custom_type_var_for_self.rs
323d1e7
@MeGaGiGaGon MeGaGiGaGon requested a review from AlexWaygood as a code owner June 20, 2025 18:56
@ntBre ntBre added the documentation Improvements or additions to documentation label Jun 20, 2025
@github-actions
Copy link
Contributor

github-actions bot commented Jun 20, 2025 •
edited
Loading

ruff-ecosystem results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

AlexWaygood
AlexWaygood reviewed Jun 20, 2025
View reviewed changes
Copy link
Member

@AlexWaygood AlexWaygood left a comment

Choose a reason for hiding this comment

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

Thanks! One of these changes feels unnecessary to me, but the rest LGTM :-)

crates/ruff_linter/src/rules/flake8_pyi/rules/custom_type_var_for_self.rs
Copy link
Member

@AlexWaygood AlexWaygood Jun 20, 2025

Choose a reason for hiding this comment

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

I'm not sure there's a need to change this file -- we just end up with a very small Fix safety section, and I think the content in that paragraph naturally fits with the content of the preceding two paragraphs. I don't think it's essential that every rule is totally consistent in the docs sections it has.

Copy link
Contributor Author

@MeGaGiGaGon MeGaGiGaGon Jun 20, 2025

Choose a reason for hiding this comment

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

The main reason I did is for the consistency - like what I've been doing, if you are writing a tool to try and detect all rules missing the section, it's a one-off edge case, since in the searching I did I could not find another rule that had this format.

Copy link
Member

@AlexWaygood AlexWaygood Jun 20, 2025

Choose a reason for hiding this comment

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

Eh, fair enough. It would certainly be nice to enforce (one day...) in CI that all rules which are sometimes unsafe have a Fix safety section in their docs explaining why.

@AlexWaygood AlexWaygood merged commit ef785d2 into astral-sh:main Jun 20, 2025
35 checks passed
@MeGaGiGaGon MeGaGiGaGon deleted the docs-normalization branch June 20, 2025 20:56
dcreager added a commit that referenced this pull request Jun 20, 2025
@dcreager
Merge branch 'main' into dcreager/tuple-spec
e5aa429 
* main:
  Handle parenthesized arguments in `remove_argument` (#18805)
  Unify helpers modules (#18835)
  Normalize some docs sections (#18831)
  [`flake8_pyi`] Fix `PYI041`'s fix causing TypeError with `None | None | ...` (#18637)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@AlexWaygood AlexWaygood AlexWaygood approved these changes

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@MeGaGiGaGon @AlexWaygood @ntBre