Quality of docstr

[estahn]

Describe the feature you'd like

Currently interrogate only checks if docstrings are present without putting any value on the quality, e.g.

• Minimum summary length
• Parameters/Args are documented
• Return is documented
• Raised exceptions are documented

I understand this would be a larger piece of work due to the different docstring styles that require parsing.

Is your feature request related to a problem?

Increase the quality of docstrings.

[ericmjl]

@estahn after submitting an issue request here, I casually browsed through the rest of the issues reported, and I saw this one. I think you may want to check pydoclint, which checks for the information you're asking for: https://github.com/jsh9/pydoclint. I also wrote a blog post about pydoclint having tried it: https://ericmjl.github.io/blog/2023/10/9/check-docstrings-blazing-fast-with-pydoclint/.

Hope this information is helpful or valuable for you!

[estahn]

@ericmjl Thanks for the pointer but I must be missing something.

def foobar(a: str) -> str:
    """
    Foobar
    """
    pass

Returns

$ pydoclint test.py --style=google
Loading config from user-specified .toml file: pyproject.toml
No config found in pyproject.toml.
Skipping files that match this pattern: \.git|\.tox
test.py
🎉 No violations 🎉

[econchick]

Belated response - my apologies!

I like this idea, and I think it'd be a good enhancement. I also think @ericmjl has an interesting idea too, that we may be able to incorporate pydoclint (esp since it also parses the AST) or at least get some inspiration.

I can't guarantee being able to add this anytime soon, so I'm inviting others to contribute to this idea. Anyone interested - please speak up and I'll assign the ticket to you. (And if/when I do start working on this before anyone else, I'll be sure to update this ticket to avoid any duplicate work).

[Saviq]

@estahn just stumbled on this :)

Thanks for the pointer but I must be missing something.

skip-checking-short-docstrings is True by default, otherwise:

$ pydoclint test.py --style=google --skip-checking-short-docstrings=False
Loading config from user-specified .toml file: pyproject.toml
File "pyproject.toml" does not exist; nothing to load.
Skipping files that match this pattern: \.git|\.tox
test.py
test.py
    1: DOC101: Function `foobar`: Docstring contains fewer arguments than in function signature.
    1: DOC103: Function `foobar`: Docstring arguments are different from function arguments. (Or could be other formatting issues: https://jsh9.github.io/pydoclint/violation_codes.html#notes-on-doc103 ). Arguments in the function signature but not in the docstring: [a: str].
    1: DOC201: Function `foobar` does not have a return section in docstring
    1: DOC203: Function `foobar` return type(s) in docstring not consistent with the return annotation. Return annotation has 1 type(s); docstring return section has 0 type(s).