language-servers/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-08-04 18:58:26 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Complete documentation for pydocstyle rules (#5387)

Browse source 
## Summary

Completes the documentation for the `pydocstyle` ruleset. Related to
#2646.

## Test Plan

`python scripts/check_docs_formatted.py`
This commit is contained in:
Tom Kuson 2023-06-27 19:12:21 +01:00 • committed by GitHub
parent 032b967b05
commit 035f8993f4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
19 changed files with 1735 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

34
crates/ruff/src/rules/pydocstyle/rules/blank_after_summary.rs
View file

@ -6,6 +6,40 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::AsRule;
/// ## What it does
/// Checks for docstring summary lines that are not separated from the docstring
/// description by one blank line.
///
/// ## Why is this bad?
/// [PEP 257] recommends that multi-line docstrings consist of "a summary line
/// just like a one-line docstring, followed by a blank line, followed by a
/// more elaborate description."
///
/// ## Example
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
/// Sort the list in ascending order and return a copy of the
/// result using the bubble sort algorithm.
/// """
/// ```
///
/// Use instead:
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the
/// result using the bubble sort algorithm.
/// """
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct BlankLineAfterSummary {
num_lines: usize,

100
crates/ruff/src/rules/pydocstyle/rules/blank_before_after_class.rs
View file

@ -10,6 +10,37 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::{AsRule, Rule};
/// ## What it does
/// Checks for docstrings on class definitions that are not preceded by a
/// blank line.
///
/// ## Why is this bad?
/// Use a blank line to separate the docstring from the class definition, for
/// consistency.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is disabled when using the `google`,
/// `numpy`, and `pep257` conventions.
///
/// For an alternative, see [D211].
///
/// ## Example
/// ```python
/// class PhotoMetadata:
/// """Metadata about a photo."""
/// ```
///
/// Use instead:
/// ```python
/// class PhotoMetadata:
///
/// """Metadata about a photo."""
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// [D211]: https://beta.ruff.rs/docs/rules/blank-line-before-class
#[violation]
pub struct OneBlankLineBeforeClass {
lines: usize,
@ -26,6 +57,44 @@ impl AlwaysAutofixableViolation for OneBlankLineBeforeClass {
}
}
/// ## What it does
/// Checks for class methods that are not separated from the class's docstring
/// by a blank line.
///
/// ## Why is this bad?
/// [PEP 257] recommends the use of a blank line to separate a class's
/// docstring its methods.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `google`
/// convention, and disabled when using the `numpy` and `pep257` conventions.
///
/// ## Example
/// ```python
/// class PhotoMetadata:
/// """Metadata about a photo."""
/// def __init__(self, file: Path):
/// ...
/// ```
///
/// Use instead:
/// ```python
/// class PhotoMetadata:
/// """Metadata about a photo."""
///
/// def __init__(self, file: Path):
/// ...
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct OneBlankLineAfterClass {
lines: usize,
@ -42,6 +111,37 @@ impl AlwaysAutofixableViolation for OneBlankLineAfterClass {
}
}
/// ## What it does
/// Checks for docstrings on class definitions that are preceded by a blank
/// line.
///
/// ## Why is this bad?
/// Avoid introducing any blank lines between a class definition and its
/// docstring, for consistency.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `google`,
/// `numpy`, and `pep257` conventions.
///
/// For an alternative, see [D203].
///
/// ## Example
/// ```python
/// class PhotoMetadata:
/// """Metadata about a photo."""
/// ```
///
/// Use instead:
/// ```python
/// class PhotoMetadata:
///
/// """Metadata about a photo."""
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// [D203]: https://beta.ruff.rs/docs/rules/one-blank-line-before-class
#[violation]
pub struct BlankLineBeforeClass {
lines: usize,

52
crates/ruff/src/rules/pydocstyle/rules/blank_before_after_function.rs
View file

@ -12,6 +12,31 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::{AsRule, Rule};
/// ## What it does
/// Checks for docstrings on functions that are separated by one or more blank
/// lines from the function definition.
///
/// ## Why is this bad?
/// Remove any blank lines between the function definition and its docstring,
/// for consistency.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
///
/// """Return the mean of the given values."""
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
#[violation]
pub struct NoBlankLineBeforeFunction {
num_lines: usize,
@ -29,6 +54,33 @@ impl AlwaysAutofixableViolation for NoBlankLineBeforeFunction {
}
}
/// ## What it does
/// Checks for docstrings on functions that are separated by one or more blank
/// lines from the function body.
///
/// ## Why is this bad?
/// Remove any blank lines between the function body and the function
/// docstring, for consistency.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
///
/// return sum(values) / len(values)
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// return sum(values) / len(values)
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
#[violation]
pub struct NoBlankLineAfterFunction {
num_lines: usize,

23
crates/ruff/src/rules/pydocstyle/rules/capitalized.rs
View file

@ -9,6 +9,29 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::AsRule;
/// ## What it does
/// Checks for docstrings that do not start with a capital letter.
///
/// ## Why is this bad?
/// The first character in a docstring should be capitalized for, grammatical
/// correctness and consistency.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """return the mean of the given values."""
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
#[violation]
pub struct FirstLineCapitalized {
first_word: String,

32
crates/ruff/src/rules/pydocstyle/rules/ends_with_period.rs
View file

@ -11,6 +11,38 @@ use crate::docstrings::Docstring;
use crate::registry::AsRule;
use crate::rules::pydocstyle::helpers::logical_line;
/// ## What it does
/// Checks for docstrings in which the first line does not end in a period.
///
/// ## Why is this bad?
/// [PEP 257] recommends that the first line of a docstring is written in the
/// form of a command, ending in a period.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `numpy` and
/// `pep257` conventions, and disabled when using the `google` convention.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values"""
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct EndsInPeriod;

31
crates/ruff/src/rules/pydocstyle/rules/ends_with_punctuation.rs
View file

@ -11,6 +11,37 @@ use crate::docstrings::Docstring;
use crate::registry::AsRule;
use crate::rules::pydocstyle::helpers::logical_line;
/// ## What it does
/// Checks for docstrings in which the first line does not end in a punctuation
/// mark, such as a period, question mark, or exclamation point.
///
/// ## Why is this bad?
/// The first line of a docstring should end with a period, question mark, or
/// exclamation point, for grammatical correctness and consistency.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `google`
/// convention, and disabled when using the `numpy` and `pep257` conventions.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values"""
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
#[violation]
pub struct EndsInPunctuation;

60
crates/ruff/src/rules/pydocstyle/rules/if_needed.rs
View file

@ -8,6 +8,66 @@ use ruff_python_semantic::{Definition, Member, MemberKind};
use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
/// ## What it does
/// Checks for `@overload` function definitions that contain a docstring.
///
/// ## Why is this bad?
/// The `@overload` decorator is used to define multiple compatible signatures
/// for a given function, to support type-checking. A series of `@overload`
/// definitions should be followed by a single non-decorated definition that
/// contains the implementation of the function.
///
/// `@overload` function definitions should not contain a docstring; instead,
/// the docstring should be placed on the non-decorated definition that contains
/// the implementation.
///
/// ## Example
/// ```python
/// from typing import overload
///
///
/// @overload
/// def factorial(n: int) -> int:
/// """Return the factorial of n."""
///
///
/// @overload
/// def factorial(n: float) -> float:
/// """Return the factorial of n."""
///
///
/// def factorial(n):
/// """Return the factorial of n."""
///
///
/// factorial.__doc__ # "Return the factorial of n."
/// ```
///
/// Use instead:
/// ```python
/// from typing import overload
///
///
/// @overload
/// def factorial(n: int) -> int:
/// ...
///
///
/// @overload
/// def factorial(n: float) -> float:
/// ...
///
///
/// def factorial(n):
/// """Return the factorial of n."""
///
///
/// factorial.__doc__ # "Return the factorial of n."
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [Python documentation: `typing.overload`](https://docs.python.org/3/library/typing.html#typing.overload)
#[violation]
pub struct OverloadWithDocstring;

98
crates/ruff/src/rules/pydocstyle/rules/indent.rs
View file

@ -10,6 +10,38 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::{AsRule, Rule};
/// ## What it does
/// Checks for docstrings that are indented with tabs.
///
/// ## Why is this bad?
/// [PEP 8](https://peps.python.org/pep-0008/#tabs-or-spaces) recommends using
/// spaces over tabs for indentation.
///
///
/// ## Example
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble
/// sort algorithm.
/// """
/// ```
///
/// Use instead:
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble
/// sort algorithm.
/// """
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
#[violation]
pub struct IndentWithSpaces;
@ -20,6 +52,39 @@ impl Violation for IndentWithSpaces {
}
}
/// ## What it does
/// Checks for under-indented docstrings.
///
/// ## Why is this bad?
/// [PEP 257] recommends that docstrings be indented to the same level as their
/// opening quotes. Avoid under-indenting docstrings, for consistency.
///
/// ## Example
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble sort
/// algorithm.
/// """
/// ```
///
/// Use instead:
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble
/// sort algorithm.
/// """
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct UnderIndentation;
@ -34,6 +99,39 @@ impl AlwaysAutofixableViolation for UnderIndentation {
}
}
/// ## What it does
/// Checks for over-indented docstrings.
///
/// ## Why is this bad?
/// [PEP 257] recommends that docstrings be indented to the same level as their
/// opening quotes. Avoid over-indenting docstrings, for consistency.
///
/// ## Example
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the
/// bubble sort algorithm.
/// """
/// ```
///
/// Use instead:
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble
/// sort algorithm.
/// """
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct OverIndentation;

80
crates/ruff/src/rules/pydocstyle/rules/multi_line_summary_start.rs
View file

@ -11,6 +11,46 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::{AsRule, Rule};
/// ## What it does
/// Checks for docstring summary lines that are not positioned on the first
/// physical line of the docstring.
///
/// ## Why is this bad?
/// [PEP 257] recommends that multi-line docstrings consist of "a summary line
/// just like a one-line docstring, followed by a blank line, followed by a
/// more elaborate description."
///
/// The summary line should be located on the first physical line of the
/// docstring, immediately after the opening quotes.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `google`
/// convention, and disabled when using the `numpy` and `pep257` conventions.
///
/// For an alternative, see [D213].
///
/// ## Example
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """
/// Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the
/// bubble sort algorithm.
/// """
/// ```
///
/// Use instead:
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble
/// sort algorithm.
/// """
/// ```
///
/// [D213]: https://beta.ruff.rs/docs/rules/multi-line-summary-second-line
#[violation]
pub struct MultiLineSummaryFirstLine;
@ -25,6 +65,46 @@ impl AlwaysAutofixableViolation for MultiLineSummaryFirstLine {
}
}
/// ## What it does
/// Checks for docstring summary lines that are not positioned on the second
/// physical line of the docstring.
///
/// ## Why is this bad?
/// [PEP 257] recommends that multi-line docstrings consist of "a summary line
/// just like a one-line docstring, followed by a blank line, followed by a
/// more elaborate description."
///
/// The summary line should be located on the second physical line of the
/// docstring, immediately after the opening quotes and the blank line.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is disabled when using the `google`,
/// `numpy`, and `pep257` conventions.
///
/// For an alternative, see [D212].
///
/// ## Example
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the
/// bubble sort algorithm.
/// """
/// ```
///
/// Use instead:
/// ```python
/// def sort_list(l: list[int]) -> list[int]:
/// """
/// Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble
/// sort algorithm.
/// """
/// ```
///
/// [D212]: https://beta.ruff.rs/docs/rules/multi-line-summary-first-line
#[violation]
pub struct MultiLineSummarySecondLine;

34
crates/ruff/src/rules/pydocstyle/rules/newline_after_last_paragraph.rs
View file

@ -10,6 +10,40 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::AsRule;
/// ## What it does
/// Checks for multi-line docstrings whose closing quotes are not on their
/// own line.
///
/// ## Why is this bad?
/// [PEP 257] recommends that the closing quotes of a multi-line docstring be
/// on their own line, for consistency and compatibility with documentation
/// tools that may need to parse the docstring.
///
/// ## Example
/// ```python
/// def sort_list(l: List[int]) -> List[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the
/// bubble sort algorithm."""
/// ```
///
/// Use instead:
/// ```python
/// def sort_list(l: List[int]) -> List[int]:
/// """Return a sorted copy of the list.
///
/// Sort the list in ascending order and return a copy of the result using the bubble
/// sort algorithm.
/// """
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct NewLineAfterLastParagraph;

34
crates/ruff/src/rules/pydocstyle/rules/no_signature.rs
View file

@ -8,6 +8,40 @@ use ruff_python_whitespace::UniversalNewlines;
use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
/// ## What it does
/// Checks for function docstrings that include the function's signature in
/// the summary line.
///
/// ## Why is this bad?
/// [PEP 257] recommends against including a function's signature in its
/// docstring. Instead, consider using type annotations as a form of
/// documentation for the function's parameters and return value.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `google` and
/// `pep257` conventions, and disabled when using the `numpy` convention.
///
/// ## Example
/// ```python
/// def foo(a, b):
/// """foo(a: int, b: int) -> list[int]"""
/// ```
///
/// Use instead:
/// ```python
/// def foo(a: int, b: int) -> list[int]:
/// """Return a list of a and b."""
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct NoSignature;

22
crates/ruff/src/rules/pydocstyle/rules/no_surrounding_whitespace.rs
View file

@ -9,6 +9,28 @@ use crate::docstrings::Docstring;
use crate::registry::AsRule;
use crate::rules::pydocstyle::helpers::ends_with_backslash;
/// ## What it does
/// Checks for surrounding whitespace in docstrings.
///
/// ## Why is this bad?
/// Remove surrounding whitespace from the docstring, for consistency.
///
/// ## Example
/// ```python
/// def factorial(n: int) -> int:
/// """ Return the factorial of n. """
/// ```
///
/// Use instead:
/// ```python
/// def factorial(n: int) -> int:
/// """Return the factorial of n."""
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
#[violation]
pub struct SurroundingWhitespace;

33
crates/ruff/src/rules/pydocstyle/rules/non_imperative_mood.rs
View file

@ -17,6 +17,39 @@ use crate::rules::pydocstyle::helpers::normalize_word;
static MOOD: Lazy<Mood> = Lazy::new(Mood::new);
/// ## What it does
/// Checks for docstring first lines that are not in an imperative mood.
///
/// ## Why is this bad?
/// [PEP 257] recommends that the first line of a docstring be written in the
/// imperative mood, for consistency.
///
/// Hint: to rewrite the docstring in the imperative, phrase the first line as
/// if it were a command.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `numpy` and
/// `pep257` conventions, and disabled when using the `google` conventions.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """Returns the mean of the given values."""
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct NonImperativeMood {
first_line: String,

23
crates/ruff/src/rules/pydocstyle/rules/not_empty.rs
View file

@ -5,6 +5,29 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::Rule;
/// ## What it does
/// Checks for empty docstrings.
///
/// ## Why is this bad?
/// An empty docstring is indicative of incomplete documentation. It should either
/// be removed or replaced with a meaningful docstring.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """"""
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
/// - [NumPy Style Guide](https://numpydoc.readthedocs.io/en/latest/format.html)
/// - [Google Python Style Guide - Docstrings](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings)
#[violation]
pub struct EmptyDocstring;

1
crates/ruff/src/rules/pydocstyle/rules/not_missing.rs
View file

@ -304,6 +304,7 @@ impl Violation for UndocumentedPublicMethod {
/// return distance / time
/// except ZeroDivisionError as exc:
/// raise FasterThanLightError from exc
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)

25
crates/ruff/src/rules/pydocstyle/rules/one_liner.rs
View file

@ -7,6 +7,31 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::registry::AsRule;
/// ## What it does
/// Checks for single-line docstrings that are broken across multiple lines.
///
/// ## Why is this bad?
/// [PEP 257] recommends that docstrings that _can_ fit on one line should be
/// formatted on a single line, for consistency and readability.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """
/// Return the mean of the given values.
/// """
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct FitsOnOneLine;

1014
crates/ruff/src/rules/pydocstyle/rules/sections.rs
View file

File diff suppressed because it is too large Load diff

33
crates/ruff/src/rules/pydocstyle/rules/starts_with_this.rs
View file

@ -5,6 +5,39 @@ use crate::checkers::ast::Checker;
use crate::docstrings::Docstring;
use crate::rules::pydocstyle::helpers::normalize_word;
/// ## What it does
/// Checks for docstrings that start with `This`.
///
/// ## Why is this bad?
/// [PEP 257] recommends that the first line of a docstring be written in the
/// imperative mood, for consistency.
///
/// Hint: to rewrite the docstring in the imperative, phrase the first line as
/// if it were a command.
///
/// This rule may not apply to all projects; its applicability is a matter of
/// convention. By default, this rule is enabled when using the `numpy`
/// convention,, and disabled when using the `google` and `pep257` conventions.
///
/// ## Example
/// ```python
/// def average(values: list[float]) -> float:
/// """This function returns the mean of the given values."""
/// ```
///
/// Use instead:
/// ```python
/// def average(values: list[float]) -> float:
/// """Return the mean of the given values."""
/// ```
///
/// ## Options
/// - `pydocstyle.convention`
///
/// ## References
/// - [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
///
/// [PEP 257]: https://peps.python.org/pep-0257/
#[violation]
pub struct DocstringStartsWithThis;

6
scripts/check_docs_formatted.py
View file

@ -33,6 +33,7 @@ KNOWN_FORMATTING_VIOLATIONS = [
"bad-quotes-inline-string",
"bad-quotes-multiline-string",
"explicit-string-concatenation",
"indent-with-spaces",
"indentation-with-invalid-multiple",
"line-too-long",
"missing-trailing-comma",
@ -44,15 +45,20 @@ KNOWN_FORMATTING_VIOLATIONS = [
"multiple-spaces-before-operator",
"multiple-statements-on-one-line-colon",
"multiple-statements-on-one-line-semicolon",
"no-blank-line-before-function",
"no-indented-block-comment",
"no-space-after-block-comment",
"no-space-after-inline-comment",
"one-blank-line-after-class",
"over-indentation",
"over-indented",
"prohibited-trailing-comma",
"shebang-leading-whitespace",
"surrounding-whitespace",
"too-few-spaces-before-inline-comment",
"trailing-comma-on-bare-tuple",
"triple-single-quotes",
"under-indentation",
"unexpected-indentation-comment",
"unicode-kind-prefix",
"unnecessary-class-parentheses",