undocumented-public-class (D101)
Derived from the pydocstyle linter.
What it does
Checks for undocumented public class definitions.
Why is this bad?
Public classes should be documented via docstrings to outline their purpose and behavior.
Generally, a class docstring should describe the class's purpose and list its public attributes and methods.
If the codebase adheres to a standard format for class docstrings, follow that format for consistency.
Example
class Player:
def __init__(self, name: str, points: int = 0) -> None:
self.name: str = name
self.points: int = points
def add_points(self, points: int) -> None:
self.points += points
Use instead (in the NumPy docstring format):
class Player:
"""A player in the game.
Attributes
----------
name : str
The name of the player.
points : int
The number of points the player has.
Methods
-------
add_points(points: int) -> None
Add points to the player's score.
"""
def __init__(self, name: str, points: int = 0) -> None:
self.name: str = name
self.points: int = points
def add_points(self, points: int) -> None:
self.points += points
Or (in the Google docstring format):
class Player:
"""A player in the game.
Attributes:
name: The name of the player.
points: The number of points the player has.
"""
def __init__(self, name: str, points: int = 0) -> None:
self.name: str = name
self.points: int = points
def add_points(self, points: int) -> None:
self.points += points