multi-line-summary-first-line (D212)
Derived from the pydocstyle linter.
Fix is always available.
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
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:
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.
"""