D417 - inconsistent results with Google-style (possible bug) #443
Description
D417 does not report for all parameters in a function docstring. Take this example file, below.
"""Something here."""
def foo(skips, verbose):
"""Do stuff.
Args:
skips (:attr:`.Skip`):
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Etiam at tellus a tellus faucibus maximus. Curabitur tellus
mauris, semper id vehicula ac, feugiat ut tortor.
verbose (bool):
If True, print out as much infromation as possible.
If False, print out concise "one-liner" information.
"""
pass
def bar(skips, verbose):
"""Do stuff.
Args:
skips (:attr:`.Skip`):
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Etiam at tellus a tellus faucibus maximus. Curabitur tellus
mauris, semper id vehicula ac, feugiat ut tortor.
verbose (bool): If True, print out as much infromation as possible.
If False, print out concise "one-liner" information.
"""
passResults
When I ran pydocstyle, it only complains with
foo.py:7 in public function `foo`:
D417: Missing argument descriptions in the docstring (argument(s) verbose are missing descriptions in 'foo' docstring)
This strikes me as inconsistent. The verbose parameter in bar is considered valid because its description starts on the same line as the parameter. skips doesn't start on the same line of the parameter in both foo and bar but pydocstyle doesn't ever complain about skips. It only seems to care about verbose.
Shouldn't pydocstyle be complaining that skips doesn't start on the same line, too?
Personally I'd prefer pydocstyle to accept that docstrings can start on the line below a parameter instead of forcing the user to write on the same like
e.g.
This is considered valid.
Args:
verbose (bool): If True, print out as much infromation as possible.
If False, print out concise "one-liner" information.
This should also be considered valid.
Args:
verbose (bool):
If True, print out as much infromation as possible.
If False, print out concise "one-liner" information.
To me, the latter feels more "right". But to be fair though, I didn't see anything in the google style guide indicating it's okay for descriptions could start one line down. So maybe you don't agree with that suggestion.
At the very least though, I'd like pydocstyle to enforce D417 consistently. skips should also be failing, which it isn't currently.
Environment Details
Python: 3.7.3
command: pydocstyle --ignore=D213,D202,D203,D406,D407 foo.py
pydocstyle version: 5.0.1