Skip to content

undocumented-public-method (D102)

Derived from the pydocstyle linter.

What it does

Checks for undocumented public method definitions.

Why is this bad?

Public methods should be documented via docstrings to outline their purpose and behavior.

Generally, a method docstring should describe the method's behavior, arguments, side effects, exceptions, return values, and any other information that may be relevant to the user.

If the codebase adheres to a standard format for method docstrings, follow that format for consistency.

Example

class Cat(Animal):
    def greet(self, happy: bool = True):
        if happy:
            print("Meow!")
        else:
            raise ValueError("Tried to greet an unhappy cat.")

Use instead (in the NumPy docstring format):

class Cat(Animal):
    def greet(self, happy: bool = True):
        """Print a greeting from the cat.

        Parameters
        ----------
        happy : bool, optional
            Whether the cat is happy, is True by default.

        Raises
        ------
        ValueError
            If the cat is not happy.
        """
        if happy:
            print("Meow!")
        else:
            raise ValueError("Tried to greet an unhappy cat.")

Or (in the Google docstring format):

class Cat(Animal):
    def greet(self, happy: bool = True):
        """Print a greeting from the cat.

        Args:
            happy: Whether the cat is happy, is True by default.

        Raises:
            ValueError: If the cat is not happy.
        """
        if happy:
            print("Meow!")
        else:
            raise ValueError("Tried to greet an unhappy cat.")

Options

References