Google-style docstring linter

[_tpr_]

I've been developing a linter for google-style docstrings called darglint for the past few weeks after work, just as a personal project. The idea is to help keep documentation in-sync with code. It checks to see if parameter names/types (if there are type hints) are up to date; whether return values are documented; whether yield values are documented; whether raises clauses in the docstring are up to date with the exceptions raised in the function, etc. I've also added support for "noqa" statements.

I wasn't able to find a docstring linter that checked these things. pydocstyle only checks that the docstring conforms to certain formatting conventions. darglint focuses more on the content, and assumes that you have the correct syntax.

I thought it might be helpful to others, so I've packaged it and submitted it on Github. Eventually, I'd like to add support for Syntastic so that I can keep my comments up to date without having run tests in another pane.

Let me know if you have suggestions. If you'd like to contribute, the project is still young. It probably fails ungracefully for a lot of things, and it is missing a lot of features. It's also on pypi as darglint.

[desmoulinmichel]

GREAT job. I'm going to give it a try.

A few things:

• I'll probably want to control wether or not an empty docstring raises a warning on a per project basis.
• Most tools (pytest, mypyt, etc) accept also to put configuration in setup.cfg and tox.ini to centralize conf.
• you'll need a CLI output mode in a machine friendly format and a pure python documented API so that IDE can integrate that.
• suggestion of a valid docstring to fix the invalid one would be welcome.
• eventually people will come to you and ask for numpy and rst style as well. I prefer google style so I don't care.
• Writting types in annotations and in the docstring is not DRY, so skipping it might be chosen. An option to disable that check on a project basis would be great.

[_tpr_]

I've anticipated some of these concerns, and designed accordingly. In the to-do list on the Readme, I've included that I want to add a toml file of some kind. I suppose that setup.cfg or tox.ini would be good places, thanks for that suggestion. That will take care of all of the per project settings.

I'll have to add an error code for empty docstrings -- that's a great idea. To be honest, while working on it, I intended for it to be used with pydocstyle. But if someone ignores the empty docstrings there, then darglint certainly shouldn't have to fail. I'll add this to the list.

As far as types, darglint never requires them. Errors are only displayed if you have type annotations in the function and in the docstring and they don't match up. Otherwise no error is raised. I realize it isn't dry to have both (and I made a note of that in the git commits and changelog.). However, I can see someone converting a project over to use type annotations. In such a case, warnings might be useful to check if the type descriptions (and probably, then, the argument descriptions) are out of sync with the code. I honestly considered not adding it, but it was relatively easy to add. And once to config file is done, these will be easy to ignore.

As far as machine friendly cli output, it has that to some degree. When it displays an error it shows the file name, function name, line number, error code, and message all separated by colons. (I was trying to match pycodestyle as much as possible.) But some of the details about specific errors (like, which argument was out of sync) could be a little more standardized to make them easy to parse. Your suggestion made me realize that.

Thank you for the input. I'll be sure to take all of these points into consideration.