Description
Following up my take docstrings violates DRY we should do our best to ensure our docstrings are correct.
First we should decide on a docstring style. From what I can see it is pretty much google style. So we should stick to it and enforce it as far as possible.
I propose adding pydoclint
. It helps with:
- signature does not match docstring arguments
- type annotation do not match docstring type annotations
- and more
There will be no errors for undocumented functions. It only checks if the docstring follows the rules if there is a docstring.
Of course, we have to decide what we want to enforce. The list of configuration options can be found here:
https://jsh9.github.io/pydoclint/config_options.html
pydoclint
is also currently in the process of being implemented in ruff
. So in the future we might be able to just use ruff
for it.
Since pydoclint
reports a lot of findings we can think of adding a "baseline", i.e. ignoreing all current warnings and enforce it for future additions.