Improve rule & options documentation (#14329)

Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>
Co-authored-by: Micha Reiser <micha@reiser.io>

crates/ruff_linter/src/rules/flake8_bandit/rules/hardcoded_tmp_directory.rs

@@ -33,6 +33,7 @@ use crate::checkers::ast::Checker;
 ///
 /// ## Options
 /// - `lint.flake8-bandit.hardcoded-tmp-directory`
+/// - `lint.flake8-bandit.hardcoded-tmp-directory-extend`
 ///
 /// ## References
 /// - [Common Weakness Enumeration: CWE-377](https://cwe.mitre.org/data/definitions/377.html)

crates/ruff_linter/src/rules/flake8_commas/rules/trailing_commas.rs

@@ -139,6 +139,12 @@ impl Context {
 ///     "baz": 2,
 /// }
 /// ```
+///
+/// ## Formatter compatibility
+/// We recommend against using this rule alongside the [formatter]. The
+/// formatter enforces consistent use of trailing commas, making the rule redundant.
+///
+/// [formatter]:https://docs.astral.sh/ruff/formatter/
 #[violation]
 pub struct MissingTrailingComma;
 
@@ -210,6 +216,12 @@ impl Violation for TrailingCommaOnBareTuple {
 /// ```python
 /// foo = (1, 2, 3)
 /// ```
+///
+/// ## Formatter compatibility
+/// We recommend against using this rule alongside the [formatter]. The
+/// formatter enforces consistent use of trailing commas, making the rule redundant.
+///
+/// [formatter]:https://docs.astral.sh/ruff/formatter/
 #[violation]
 pub struct ProhibitedTrailingComma;
 

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

@@ -34,6 +34,20 @@ use crate::Locator;
 /// ```python
 /// z = "The quick brown fox."
 /// ```
+///
+/// # Formatter compatibility
+/// Use of this rule alongside the [formatter] must be handled with care.
+/// Currently, the [formatter] can introduce new single-line implicitly
+/// concatenated strings, therefore we suggest rerunning the linter and
+/// [formatter] in the following order:
+/// 1. Run the linter with this rule (`ISC001`) disabled
+/// 2. Run the [formatter]
+/// 3. Rerun the linter with this rule (`ISC001`) enabled
+/// This is one of very few cases where the [formatter] can produce code that
+/// contains lint violations. It is a known issue that should be resolved by the
+/// new 2025 style guide.
+///
+/// [formatter]:https://docs.astral.sh/ruff/formatter/
 #[violation]
 pub struct SingleLineImplicitStringConcatenation;
 
@@ -81,7 +95,20 @@ impl Violation for SingleLineImplicitStringConcatenation {
 /// ## Options
 /// - `lint.flake8-implicit-str-concat.allow-multiline`
 ///
+/// # Formatter compatibility
+/// Use of this rule alongside the [formatter] must be handled with care.
+/// Currently, the [formatter] can introduce new multi-line implicitly
+/// concatenated strings, therefore we suggest rerunning the linter and
+/// [formatter] in the following order:
+/// 1. Run the linter with this rule (`ISC002`) disabled
+/// 2. Run the [formatter]
+/// 3. Rerun the linter with this rule (`ISC002`) enabled
+/// This is one of very few cases where the [formatter] can produce code that
+/// contains lint violations. It is a known issue that should be resolved by the
+/// new 2025 style guide.
+///
 /// [PEP 8]: https://peps.python.org/pep-0008/#maximum-line-length
+/// [formatter]:https://docs.astral.sh/ruff/formatter/
 #[violation]
 pub struct MultiLineImplicitStringConcatenation;
 

crates/ruff_linter/src/rules/pycodestyle/rules/logical_lines/indentation.rs

@@ -23,7 +23,6 @@ use super::LogicalLine;
 ///     a = 1
 /// ```
 ///
-///
 /// ## Formatter compatibility
 /// We recommend against using this rule alongside the [formatter]. The
 /// formatter enforces consistent indentation, making the rule redundant.
@@ -232,7 +231,12 @@ impl Violation for UnexpectedIndentationComment {
 ///     pass
 /// ```
 ///
+/// ## Formatter compatibility
+/// We recommend against using this rule alongside the [formatter]. The
+/// formatter enforces consistent indentation, making the rule redundant.
+///
 /// [PEP 8]: https://peps.python.org/pep-0008/#indentation
+/// [formatter]:https://docs.astral.sh/ruff/formatter/
 #[violation]
 pub struct OverIndented {
     is_comment: bool,

crates/ruff_linter/src/rules/pydocstyle/rules/sections.rs

@@ -36,6 +36,9 @@ use crate::rules::pydocstyle::settings::Convention;
 /// indentation of the docstring's opening quotes, and the body should be
 /// indented one level further.
 ///
+/// This rule is enabled when using the `numpy` and `google` conventions, and
+/// disabled when using the `pep257` convention.
+///
 /// ## Example
 /// ```python
 /// def calculate_speed(distance: float, time: float) -> float:
@@ -219,6 +222,9 @@ impl AlwaysFixableViolation for SectionUnderlineNotOverIndented {
 /// a blank line, followed by a series of sections. Each section typically has
 /// a header and a body.
 ///
+/// This rule is enabled when using the `numpy` and `google` conventions, and
+/// disabled when using the `pep257` convention.
+///
 /// ## Example
 /// ```python
 /// def calculate_speed(distance: float, time: float) -> float:
@@ -1049,9 +1055,6 @@ impl AlwaysFixableViolation for BlankLineAfterLastSection {
 ///         raise FasterThanLightError from exc
 /// ```
 ///
-/// ## Options
-/// - `lint.pydocstyle.convention`
-///
 /// ## References
 /// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
 /// - [PEP 287 – reStructuredText Docstring Format](https://peps.python.org/pep-0287/)
@@ -1294,9 +1297,6 @@ impl Violation for UndocumentedParam {
 ///         raise FasterThanLightError from exc
 /// ```
 ///
-/// ## Options
-/// - `lint.pydocstyle.convention`
-///
 /// ## References
 /// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
 /// - [PEP 287 – reStructuredText Docstring Format](https://peps.python.org/pep-0287/)

crates/ruff_workspace/src/options.rs

@@ -1007,7 +1007,7 @@ impl Flake8AnnotationsOptions {
 #[serde(deny_unknown_fields, rename_all = "kebab-case")]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub struct Flake8BanditOptions {
-    /// A list of directories to consider temporary.
+    /// A list of directories to consider temporary (see `S108`).
     #[option(
         default = "[\"/tmp\", \"/var/tmp\", \"/dev/shm\"]",
         value_type = "list[str]",
@@ -1016,7 +1016,7 @@ pub struct Flake8BanditOptions {
     pub hardcoded_tmp_directory: Option<Vec<String>>,
 
     /// A list of directories to consider temporary, in addition to those
-    /// specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory).
+    /// specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory) (see `S108`).
     #[option(
         default = "[]",
         value_type = "list[str]",
@@ -2099,7 +2099,7 @@ pub struct IsortOptions {
     /// Use `-1` for automatic determination.
     ///
     /// Ruff uses at most one blank line after imports in typing stub files (files with `.pyi` extension) in accordance to
-    /// the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/source/stubs.html#blank-lines)).
+    /// the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#blank-lines)).
     ///
     /// When using the formatter, only the values `-1`, `1`, and `2` are compatible because
     /// it enforces at least one empty and at most two empty lines after imports.

ruff.schema.json

@@ -948,7 +948,7 @@
           ]
         },
         "hardcoded-tmp-directory": {
-          "description": "A list of directories to consider temporary.",
+          "description": "A list of directories to consider temporary (see `S108`).",
           "type": [
             "array",
             "null"
@@ -958,7 +958,7 @@
           }
         },
         "hardcoded-tmp-directory-extend": {
-          "description": "A list of directories to consider temporary, in addition to those specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory).",
+          "description": "A list of directories to consider temporary, in addition to those specified by [`hardcoded-tmp-directory`](#lint_flake8-bandit_hardcoded-tmp-directory) (see `S108`).",
           "type": [
             "array",
             "null"
@@ -1700,7 +1700,7 @@
           ]
         },
         "lines-after-imports": {
-          "description": "The number of blank lines to place after imports. Use `-1` for automatic determination.\n\nRuff uses at most one blank line after imports in typing stub files (files with `.pyi` extension) in accordance to the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/source/stubs.html#blank-lines)).\n\nWhen using the formatter, only the values `-1`, `1`, and `2` are compatible because it enforces at least one empty and at most two empty lines after imports.",
+          "description": "The number of blank lines to place after imports. Use `-1` for automatic determination.\n\nRuff uses at most one blank line after imports in typing stub files (files with `.pyi` extension) in accordance to the typing style recommendations ([source](https://typing.readthedocs.io/en/latest/guides/writing_stubs.html#blank-lines)).\n\nWhen using the formatter, only the values `-1`, `1`, and `2` are compatible because it enforces at least one empty and at most two empty lines after imports.",
           "type": [
             "integer",
             "null"