Uniformly put ## Options at the end of documentation (#5104)

crates/ruff/src/rules/eradicate/rules/commented_out_code.rs

@@ -14,13 +14,13 @@ use super::super::detection::comment_contains_code;
 /// Commented-out code is dead code, and is often included inadvertently.
 /// It should be removed.
 ///
-/// ## Options
-/// - `task-tags`
-///
 /// ## Example
 /// ```python
 /// # print('foo')
 /// ```
+///
+/// ## Options
+/// - `task-tags`
 #[violation]
 pub struct CommentedOutCode;
 

crates/ruff/src/rules/flake8_bugbear/rules/function_call_argument_default.rs

@@ -21,9 +21,6 @@ use crate::rules::flake8_bugbear::rules::mutable_argument_default::is_mutable_fu
 /// once, at definition time. The returned value will then be reused by all
 /// calls to the function, which can lead to unexpected behaviour.
 ///
-/// ## Options
-/// - `flake8-bugbear.extend-immutable-calls`
-///
 /// ## Example
 /// ```python
 /// def create_list() -> list[int]:
@@ -45,16 +42,8 @@ use crate::rules::flake8_bugbear::rules::mutable_argument_default::is_mutable_fu
 ///     return arg
 /// ```
 ///
-/// Alternatively, if shared behavior is desirable, clarify the intent by
-/// assigning to a module-level variable:
-/// ```python
-/// I_KNOW_THIS_IS_SHARED_STATE = create_list()
-///
-///
-/// def mutable_default(arg: list[int] = I_KNOW_THIS_IS_SHARED_STATE) -> list[int]:
-///     arg.append(4)
-///     return arg
-/// ```
+/// ## Options
+/// - `flake8-bugbear.extend-immutable-calls`
 #[violation]
 pub struct FunctionCallInDefaultArgument {
     pub name: Option<String>,

crates/ruff/src/rules/flake8_builtins/rules/builtin_argument_shadowing.rs

@@ -20,10 +20,6 @@ use super::super::helpers::shadows_builtin;
 /// Builtins can be marked as exceptions to this rule via the
 /// [`flake8-builtins.builtins-ignorelist`] configuration option.
 ///
-/// ## Options
-///
-/// - `flake8-builtins.builtins-ignorelist`
-///
 /// ## Example
 /// ```python
 /// def remove_duplicates(list, list2):
@@ -46,6 +42,9 @@ use super::super::helpers::shadows_builtin;
 ///     return list(result)
 /// ```
 ///
+/// ## Options
+/// - `flake8-builtins.builtins-ignorelist`
+///
 /// ## References
 /// - [_Is it bad practice to use a built-in function name as an attribute or method identifier?_](https://stackoverflow.com/questions/9109333/is-it-bad-practice-to-use-a-built-in-function-name-as-an-attribute-or-method-ide)
 /// - [_Why is it a bad idea to name a variable `id` in Python?_](https://stackoverflow.com/questions/77552/id-is-a-bad-variable-name-in-python)

crates/ruff/src/rules/flake8_builtins/rules/builtin_attribute_shadowing.rs

@@ -20,10 +20,6 @@ use super::super::helpers::{shadows_builtin, AnyShadowing};
 /// [`flake8-builtins.builtins-ignorelist`] configuration option, or
 /// converted to the appropriate dunder method.
 ///
-/// ## Options
-///
-/// - `flake8-builtins.builtins-ignorelist`
-///
 /// ## Example
 /// ```python
 /// class Shadow:
@@ -46,6 +42,9 @@ use super::super::helpers::{shadows_builtin, AnyShadowing};
 ///         return 0
 /// ```
 ///
+/// ## Options
+/// - `flake8-builtins.builtins-ignorelist`
+///
 /// ## References
 /// - [_Is it bad practice to use a built-in function name as an attribute or method identifier?_](https://stackoverflow.com/questions/9109333/is-it-bad-practice-to-use-a-built-in-function-name-as-an-attribute-or-method-ide)
 /// - [_Why is it a bad idea to name a variable `id` in Python?_](https://stackoverflow.com/questions/77552/id-is-a-bad-variable-name-in-python)

crates/ruff/src/rules/flake8_builtins/rules/builtin_variable_shadowing.rs

@@ -19,10 +19,6 @@ use super::super::helpers::{shadows_builtin, AnyShadowing};
 /// Builtins can be marked as exceptions to this rule via the
 /// [`flake8-builtins.builtins-ignorelist`] configuration option.
 ///
-/// ## Options
-///
-/// - `flake8-builtins.builtins-ignorelist`
-///
 /// ## Example
 /// ```python
 /// def find_max(list_of_lists):
@@ -43,6 +39,10 @@ use super::super::helpers::{shadows_builtin, AnyShadowing};
 ///     return result
 /// ```
 ///
+/// ## Options
+/// - `flake8-builtins.builtins-ignorelist`
+///
+/// ## References
 /// - [_Why is it a bad idea to name a variable `id` in Python?_](https://stackoverflow.com/questions/77552/id-is-a-bad-variable-name-in-python)
 #[violation]
 pub struct BuiltinVariableShadowing {

crates/ruff/src/rules/flake8_implicit_str_concat/rules/implicit.rs

@@ -61,9 +61,6 @@ impl Violation for SingleLineImplicitStringConcatenation {
 /// altogether, set the `flake8-implicit-str-concat.allow-multiline` option
 /// to `false`.
 ///
-/// ## Options
-/// - `flake8-implicit-str-concat.allow-multiline`
-///
 /// ## Example
 /// ```python
 /// z = "The quick brown fox jumps over the lazy "\
@@ -78,6 +75,9 @@ impl Violation for SingleLineImplicitStringConcatenation {
 /// )
 /// ```
 ///
+/// ## Options
+/// - `flake8-implicit-str-concat.allow-multiline`
+///
 /// ## References
 /// - [PEP 8](https://peps.python.org/pep-0008/#maximum-line-length)
 #[violation]

crates/ruff/src/rules/flake8_quotes/rules/from_tokens.rs

@@ -20,9 +20,6 @@ use super::super::settings::Quote;
 /// Consistency is good. Use either single or double quotes for inline
 /// strings, but be consistent.
 ///
-/// ## Options
-/// - `flake8-quotes.inline-quotes`
-///
 /// ## Example
 /// ```python
 /// foo = 'bar'
@@ -32,6 +29,9 @@ use super::super::settings::Quote;
 /// ```python
 /// foo = "bar"
 /// ```
+///
+/// ## Options
+/// - `flake8-quotes.inline-quotes`
 #[violation]
 pub struct BadQuotesInlineString {
     quote: Quote,
@@ -65,9 +65,6 @@ impl AlwaysAutofixableViolation for BadQuotesInlineString {
 /// Consistency is good. Use either single or double quotes for multiline
 /// strings, but be consistent.
 ///
-/// ## Options
-/// - `flake8-quotes.multiline-quotes`
-///
 /// ## Example
 /// ```python
 /// foo = '''
@@ -81,6 +78,9 @@ impl AlwaysAutofixableViolation for BadQuotesInlineString {
 /// bar
 /// """
 /// ```
+///
+/// ## Options
+/// - `flake8-quotes.multiline-quotes`
 #[violation]
 pub struct BadQuotesMultilineString {
     quote: Quote,
@@ -113,9 +113,6 @@ impl AlwaysAutofixableViolation for BadQuotesMultilineString {
 /// Consistency is good. Use either single or double quotes for docstring
 /// strings, but be consistent.
 ///
-/// ## Options
-/// - `flake8-quotes.docstring-quotes`
-///
 /// ## Example
 /// ```python
 /// '''
@@ -129,6 +126,9 @@ impl AlwaysAutofixableViolation for BadQuotesMultilineString {
 /// bar
 /// """
 /// ```
+///
+/// ## Options
+/// - `flake8-quotes.docstring-quotes`
 #[violation]
 pub struct BadQuotesDocstring {
     quote: Quote,

crates/ruff/src/rules/flake8_self/rules/private_member_access.rs

@@ -20,9 +20,6 @@ use crate::checkers::ast::Checker;
 /// versions, that it will have the same type, or that it will have the same
 /// behavior. Instead, use the class's public interface.
 ///
-/// ## Options
-/// - `flake8-self.ignore-names`
-///
 /// ## Example
 /// ```python
 /// class Class:
@@ -45,6 +42,9 @@ use crate::checkers::ast::Checker;
 /// print(var.public_member)
 /// ```
 ///
+/// ## Options
+/// - `flake8-self.ignore-names`
+///
 /// ## References
 /// - [_What is the meaning of single or double underscores before an object name?_](https://stackoverflow.com/questions/1301346/what-is-the-meaning-of-single-and-double-underscore-before-an-object-name)
 #[violation]

crates/ruff/src/rules/flake8_tidy_imports/rules/relative_imports.rs

@@ -31,9 +31,6 @@ use crate::rules::flake8_tidy_imports::settings::Strictness;
 /// > from .sibling import example
 /// > ```
 ///
-/// ## Options
-/// - `flake8-tidy-imports.ban-relative-imports`
-///
 /// ## Example
 /// ```python
 /// from .. import foo
@@ -44,6 +41,9 @@ use crate::rules::flake8_tidy_imports::settings::Strictness;
 /// from mypkg import foo
 /// ```
 ///
+/// ## Options
+/// - `flake8-tidy-imports.ban-relative-imports`
+///
 /// [PEP 8]: https://peps.python.org/pep-0008/#imports
 #[violation]
 pub struct RelativeImports {

crates/ruff/src/rules/mccabe/rules/function_is_too_complex.rs

@@ -8,18 +8,15 @@ use ruff_python_ast::source_code::Locator;
 /// ## What it does
 /// Checks for functions with a high `McCabe` complexity.
 ///
+/// ## Why is this bad?
 /// The `McCabe` complexity of a function is a measure of the complexity of
 /// the control flow graph of the function. It is calculated by adding
 /// one to the number of decision points in the function. A decision
 /// point is a place in the code where the program has a choice of two
 /// or more paths to follow.
 ///
-/// ## Why is this bad?
 /// Functions with a high complexity are hard to understand and maintain.
 ///
-/// ## Options
-/// - `mccabe.max-complexity`
-///
 /// ## Example
 /// ```python
 /// def foo(a, b, c):
@@ -46,6 +43,9 @@ use ruff_python_ast::source_code::Locator;
 ///         return 2
 ///     return 1
 /// ```
+///
+/// ## Options
+/// - `mccabe.max-complexity`
 #[violation]
 pub struct ComplexStructure {
     name: String,

crates/ruff/src/rules/pep8_naming/rules/invalid_first_argument_name_for_class_method.rs

@@ -21,11 +21,6 @@ use crate::checkers::ast::Checker;
 /// > append a single trailing underscore rather than use an abbreviation or spelling corruption.
 /// > Thus `class_` is better than `clss`. (Perhaps better is to avoid such clashes by using a synonym.)
 ///
-/// ## Options
-/// - `pep8-naming.classmethod-decorators`
-/// - `pep8-naming.staticmethod-decorators`
-/// - `pep8-naming.ignore-names`
-///
 /// ## Example
 /// ```python
 /// class Example:
@@ -42,8 +37,12 @@ use crate::checkers::ast::Checker;
 ///         ...
 /// ```
 ///
-/// [PEP 8]: https://peps.python.org/pep-0008/#function-and-method-arguments
+/// ## Options
+/// - `pep8-naming.classmethod-decorators`
+/// - `pep8-naming.staticmethod-decorators`
+/// - `pep8-naming.ignore-names`
 ///
+/// [PEP 8]: https://peps.python.org/pep-0008/#function-and-method-arguments
 #[violation]
 pub struct InvalidFirstArgumentNameForClassMethod;
 

crates/ruff/src/rules/pep8_naming/rules/invalid_first_argument_name_for_method.rs

@@ -21,11 +21,6 @@ use crate::checkers::ast::Checker;
 /// > append a single trailing underscore rather than use an abbreviation or spelling corruption.
 /// > Thus `class_` is better than `clss`. (Perhaps better is to avoid such clashes by using a synonym.)
 ///
-/// ## Options
-/// - `pep8-naming.classmethod-decorators`
-/// - `pep8-naming.staticmethod-decorators`
-/// - `pep8-naming.ignore-names`
-///
 /// ## Example
 /// ```python
 /// class Example:
@@ -40,6 +35,11 @@ use crate::checkers::ast::Checker;
 ///         ...
 /// ```
 ///
+/// ## Options
+/// - `pep8-naming.classmethod-decorators`
+/// - `pep8-naming.staticmethod-decorators`
+/// - `pep8-naming.ignore-names`
+///
 /// [PEP 8]: https://peps.python.org/pep-0008/#function-and-method-arguments
 #[violation]
 pub struct InvalidFirstArgumentNameForMethod;

crates/ruff/src/rules/pep8_naming/rules/invalid_function_name.rs

@@ -20,9 +20,6 @@ use crate::settings::types::IdentifierPattern;
 /// > improve readability. mixedCase is allowed only in contexts where that’s already the
 /// > prevailing style (e.g. threading.py), to retain backwards compatibility.
 ///
-/// ## Options
-/// - `pep8-naming.ignore-names`
-///
 /// ## Example
 /// ```python
 /// def myFunction():
@@ -35,6 +32,9 @@ use crate::settings::types::IdentifierPattern;
 ///     pass
 /// ```
 ///
+/// ## Options
+/// - `pep8-naming.ignore-names`
+///
 /// [PEP 8]: https://peps.python.org/pep-0008/#function-and-variable-names
 #[violation]
 pub struct InvalidFunctionName {

crates/ruff/src/rules/pep8_naming/rules/non_lowercase_variable_in_function.rs

@@ -17,9 +17,6 @@ use crate::rules::pep8_naming::helpers;
 /// > is allowed only in contexts where that's already the prevailing style (e.g. threading.py),
 /// > to retain backwards compatibility.
 ///
-/// ## Options
-/// - `pep8-naming.ignore-names`
-///
 /// ## Example
 /// ```python
 /// def my_function(a):
@@ -34,6 +31,9 @@ use crate::rules::pep8_naming::helpers;
 ///     return b
 /// ```
 ///
+/// ## Options
+/// - `pep8-naming.ignore-names`
+///
 /// [PEP 8]: https://peps.python.org/pep-0008/#function-and-variable-names
 #[violation]
 pub struct NonLowercaseVariableInFunction {

crates/ruff/src/rules/pycodestyle/rules/line_too_long.rs

@@ -11,9 +11,6 @@ use crate::settings::Settings;
 /// ## Why is this bad?
 /// Overlong lines can hurt readability.
 ///
-/// ## Options
-/// - `task-tags`
-///
 /// ## Example
 /// ```python
 /// my_function(param1, param2, param3, param4, param5, param6, param7, param8, param9, param10)
@@ -26,6 +23,9 @@ use crate::settings::Settings;
 ///     param6, param7, param8, param9, param10
 /// )
 /// ```
+///
+/// ## Options
+/// - `task-tags`
 #[violation]
 pub struct LineTooLong(pub usize, pub usize);
 

crates/ruff/src/rules/pyflakes/rules/unused_import.rs

@@ -26,10 +26,6 @@ enum UnusedImportContext {
 /// If an import statement is used to check for the availability or existence
 /// of a module, consider using `importlib.util.find_spec` instead.
 ///
-/// ## Options
-///
-/// - `pyflakes.extend-generics`
-///
 /// ## Example
 /// ```python
 /// import numpy as np  # unused import
@@ -55,6 +51,9 @@ enum UnusedImportContext {
 ///     print("numpy is not installed")
 /// ```
 ///
+/// ## Options
+/// - `pyflakes.extend-generics`
+///
 /// ## References
 /// - [Python documentation: `import`](https://docs.python.org/3/reference/simple_stmts.html#the-import-statement)
 /// - [Python documentation: `importlib.util.find_spec`](https://docs.python.org/3/library/importlib.html#importlib.util.find_spec)

crates/ruff/src/rules/pyflakes/rules/unused_variable.rs

@@ -24,9 +24,6 @@ use crate::registry::AsRule;
 /// prefixed with an underscore, or some other value that adheres to the
 /// [`dummy-variable-rgx`] pattern.
 ///
-/// ## Options
-/// - `dummy-variable-rgx`
-///
 /// ## Example
 /// ```python
 /// def foo():
@@ -41,6 +38,9 @@ use crate::registry::AsRule;
 ///     x = 1
 ///     return x
 /// ```
+///
+/// ## Options
+/// - `dummy-variable-rgx`
 #[violation]
 pub struct UnusedVariable {
     pub name: String,

crates/ruff/src/rules/ruff/rules/function_call_in_dataclass_default.rs

@@ -23,9 +23,6 @@ use crate::rules::ruff::rules::helpers::{
 /// If a field needs to be initialized with a mutable object, use the
 /// `field(default_factory=...)` pattern.
 ///
-/// ## Options
-/// - `flake8-bugbear.extend-immutable-calls`
-///
 /// ## Examples
 /// ```python
 /// from dataclasses import dataclass
@@ -53,6 +50,9 @@ use crate::rules::ruff::rules::helpers::{
 /// class A:
 ///     mutable_default: list[int] = field(default_factory=creating_list)
 /// ```
+///
+/// ## Options
+/// - `flake8-bugbear.extend-immutable-calls`
 #[violation]
 pub struct FunctionCallInDataclassDefaultArgument {
     pub name: Option<String>,