Skip to content

automatic checks on docstrings #577

Open
@XzzX

Description

@XzzX

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions