PyCQA/pydocstyle

Google style hanging indent on line break

sebastian-correa opened this issue · 0 comments

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

  • Mac OS 12.5.1 on an Intel Mac.
  • Python 3.10.8.
  • pydocstyle 6.2.2.