search

terrencepreilly / darglint

A python documentation linter which checks that the docstring description matches the definition.
MIT License
481 stars 41 forks source link

Detecting completely missing docstrings #155

Closed cristianmtr closed 3 years ago

cristianmtr commented 3 years ago

Hey

this doesn't seem to catch completely missing docstrings. Am I missing something?

linting this

def me(x):
    print(x)

does not find any problems

If I do add a basic docstring it detects the missing params

def me(x):
    """smth"""
    print(x)
darglint -s sphinx -z full -v 2 /home/cristian/.config/JetBrains/PyCharm2020.3/scratches/scratch.py
/home/cristian/.config/JetBrains/PyCharm2020.3/scratches/scratch.py:me:1: DAR101: Missing parameter(s) in Docstring: - x
terrencepreilly commented 3 years ago

Yes, that's by design. See scope in the readme. Since this is something covered by pydocstyle (See their error codes), it's not added to darglint. Darglint's purpose is to check if docstrings are accurate, not to enforce their presence.

We could probably add it as an disabled-by-default error, even if it's not really in scope for the program. For the moment, though, it doesn't seem necessary.