diff --git a/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs b/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs index 185071638493b..09cf6869a08eb 100644 --- a/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs +++ b/crates/ruff_linter/src/rules/pydoclint/rules/check_docstring.rs @@ -15,7 +15,7 @@ use crate::registry::Rule; use crate::rules::pydocstyle::settings::Convention; /// ## What it does -/// Checks for functions with explicit returns missing a returns section in +/// Checks for functions with explicit returns missing a "returns" section in /// their docstring. /// /// ## Why is this bad? @@ -59,7 +59,7 @@ impl Violation for DocstringMissingReturns { } /// ## What it does -/// Checks for function docstrings that have a returns section without +/// Checks for function docstrings that have a "returns" section without /// needing one. /// /// ## Why is this bad? @@ -103,7 +103,7 @@ impl Violation for DocstringExtraneousReturns { } /// ## What it does -/// Checks for functions with yield statements missing a yields section in +/// Checks for functions with yield statements missing a "yields" section in /// their docstring. /// /// ## Why is this bad? @@ -113,27 +113,27 @@ impl Violation for DocstringExtraneousReturns { /// ## Example /// ```python /// def count_to_n(n: int) -> int: -/// """Generate integers up to n. +/// """Generate integers up to *n*. /// /// Args: -/// n: Max integer. +/// n: The number at which to stop counting. /// """ -/// for i in range(n): +/// for i in range(1, n + 1): /// yield i /// ``` /// /// Use instead: /// ```python /// def count_to_n(n: int) -> int: -/// """Generate integers up to n. +/// """Generate integers up to *n*. /// /// Args: -/// n: Max integer. +/// n: The number at which to stop counting. /// /// Yields: -/// int: The ith integer. +/// int: The number we're at in the count. /// """ -/// for i in range(n): +/// for i in range(1, n + 1): /// yield i /// ``` #[violation] @@ -144,10 +144,14 @@ impl Violation for DocstringMissingYields { fn message(&self) -> String { format!("`yield` is not documented in docstring") } + + fn fix_title(&self) -> Option { + Some(format!("Add a \"Yields\" section to the docstring")) + } } /// ## What it does -/// Checks for function docstrings that have a yields section without +/// Checks for function docstrings that have a "yields" section without /// needing one. /// /// ## Why is this bad? @@ -186,13 +190,17 @@ pub struct DocstringExtraneousYields; impl Violation for DocstringExtraneousYields { #[derive_message_formats] fn message(&self) -> String { - format!("Docstring should not have a yields section because the function doesn't yield anything") + format!("Docstring has a \"Yields\" section but the function doesn't yield anything") + } + + fn fix_title(&self) -> Option { + Some(format!("Remove the \"Yields\" section")) } } /// ## What it does /// Checks for function docstrings that do not include documentation for all -/// explicitly-raised exceptions. +/// explicitly raised exceptions. /// /// ## Why is this bad? /// If a function raises an exception without documenting it in its docstring, @@ -367,7 +375,7 @@ impl<'a> DocstringSections<'a> { let mut returns: Option = None; let mut yields: Option = None; let mut raises: Option = None; - for section in sections.iter() { + for section in sections { match section.kind() { SectionKind::Raises => raises = Some(RaisesSection::from_section(§ion, style)), SectionKind::Returns => returns = Some(GenericSection::from_section(§ion)), diff --git a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_google.py.snap b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_google.py.snap index 3ee75598a189e..2c3c651b226ff 100644 --- a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_google.py.snap +++ b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_google.py.snap @@ -1,7 +1,7 @@ --- source: crates/ruff_linter/src/rules/pydoclint/mod.rs --- -DOC403_google.py:20:1: DOC403 Docstring should not have a yields section because the function doesn't yield anything +DOC403_google.py:20:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything | 18 | num (int): A number 19 | @@ -11,8 +11,9 @@ DOC403_google.py:20:1: DOC403 Docstring should not have a yields section because | |____^ DOC403 23 | print('test') | + = help: Remove the "Yields" section -DOC403_google.py:36:1: DOC403 Docstring should not have a yields section because the function doesn't yield anything +DOC403_google.py:36:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything | 34 | num (int): A number 35 | @@ -22,3 +23,4 @@ DOC403_google.py:36:1: DOC403 Docstring should not have a yields section because | |________^ DOC403 39 | print('test') | + = help: Remove the "Yields" section diff --git a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_numpy.py.snap b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_numpy.py.snap index 394f7c7ca38df..aff49d2869d95 100644 --- a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_numpy.py.snap +++ b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-extraneous-yields_DOC403_numpy.py.snap @@ -1,7 +1,7 @@ --- source: crates/ruff_linter/src/rules/pydoclint/mod.rs --- -DOC403_numpy.py:24:1: DOC403 Docstring should not have a yields section because the function doesn't yield anything +DOC403_numpy.py:24:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything | 22 | A number 23 | @@ -13,8 +13,9 @@ DOC403_numpy.py:24:1: DOC403 Docstring should not have a yields section because | |____^ DOC403 29 | print('test') | + = help: Remove the "Yields" section -DOC403_numpy.py:44:1: DOC403 Docstring should not have a yields section because the function doesn't yield anything +DOC403_numpy.py:44:1: DOC403 Docstring has a "Yields" section but the function doesn't yield anything | 42 | A number 43 | @@ -26,3 +27,4 @@ DOC403_numpy.py:44:1: DOC403 Docstring should not have a yields section because | |________^ DOC403 49 | print('test') | + = help: Remove the "Yields" section diff --git a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_google.py.snap b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_google.py.snap index 8226ed16ff95e..c9ebc3f280864 100644 --- a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_google.py.snap +++ b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_google.py.snap @@ -8,6 +8,7 @@ DOC402_google.py:9:5: DOC402 `yield` is not documented in docstring 9 | yield 'test' | ^^^^^^^^^^^^ DOC402 | + = help: Add a "Yields" section to the docstring DOC402_google.py:50:9: DOC402 `yield` is not documented in docstring | @@ -16,6 +17,7 @@ DOC402_google.py:50:9: DOC402 `yield` is not documented in docstring 50 | yield 'test' | ^^^^^^^^^^^^ DOC402 | + = help: Add a "Yields" section to the docstring DOC402_google.py:59:9: DOC402 `yield` is not documented in docstring | @@ -26,6 +28,7 @@ DOC402_google.py:59:9: DOC402 `yield` is not documented in docstring 60 | 61 | print("I never yield") | + = help: Add a "Yields" section to the docstring DOC402_google.py:67:5: DOC402 `yield` is not documented in docstring | @@ -34,3 +37,4 @@ DOC402_google.py:67:5: DOC402 `yield` is not documented in docstring 67 | yield from range(10) | ^^^^^^^^^^^^^^^^^^^^ DOC402 | + = help: Add a "Yields" section to the docstring diff --git a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_numpy.py.snap b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_numpy.py.snap index 55233c7db09c0..4737fe16037ce 100644 --- a/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_numpy.py.snap +++ b/crates/ruff_linter/src/rules/pydoclint/snapshots/ruff_linter__rules__pydoclint__tests__docstring-missing-yields_DOC402_numpy.py.snap @@ -8,6 +8,7 @@ DOC402_numpy.py:11:5: DOC402 `yield` is not documented in docstring 11 | yield 'test' | ^^^^^^^^^^^^ DOC402 | + = help: Add a "Yields" section to the docstring DOC402_numpy.py:62:9: DOC402 `yield` is not documented in docstring | @@ -16,3 +17,4 @@ DOC402_numpy.py:62:9: DOC402 `yield` is not documented in docstring 62 | yield 'test' | ^^^^^^^^^^^^ DOC402 | + = help: Add a "Yields" section to the docstring