PyCQA / pydocstyle

docstring style checker
http://pydocstyle.org
MIT License
1.11k stars 188 forks source link

Google style hanging indent on line break #625

Open sebastian-correa opened 1 year ago

sebastian-correa commented 1 year ago

Issue

According to Google's Style Guide, if a line in the Args section needs to be broken due to length, you should use a hanging indent for the next lines [ref].

If the description is too long to fit on a single 80-character line, use a hanging indent of 2 or 4 spaces more than the parameter name (be consistent with the rest of the docstrings in the file).

I guess this is also the case for other valid sections in the docstring.

Example

This must be a case of misconfiguration, but running pydocstyle --convetion=google doesn't suggest those fixes in my case. For example, I would expect the following docstring

def add(a: int, b: int) -> int:
    """Add a and b.

    Args:
        a (int): Number 1 to be added. This line is intentionally long to cause
         a mandatory break.
        b (int): Number 2 to be added. This line is intentionally long to cause
        a mandatory break.
    """
    return a + b

to be flagged as incorrect because the correct Google-style docstring would be

def add(a: int, b: int) -> int:
    """Add a and b.

    Args:
        a (int): Number 1 to be added. This line is intentionally long to cause
            a mandatory break.
        b (int): Number 2 to be added. This line is intentionally long to cause
            a mandatory break.
    """
    return a + b

Instead, pydocstyle doesn't complain.

The correct hanging indent can be detected by measuring the hanging indent between Args: and the first arg, for example.

Am I doing something wrong?

Environment