Mridang Agarwalla Mridang Agarwalla - 24 days ago 6
Python Question

How do I disable "missing docstring" warnings at a file-level in Pylint?

Pylint throws errors that some of files are missing docstrings. I try and add docstrings to each class, method and function but it seems that Pylint also checks that files should a docstring at the beginning of it. Can i disable this somehow? I would like to be notified of a docstring is missing inside a class, function or method but it shouldn't be mandatory for a file to have a docstring.

(Is there a term of the legal jargon often found at the beginning of a proprietary source file? Any examples? I don't know whether it is a okay to post such a trivial question separately.)

Answer

It is nice for a Python module to have a docstring, explaining what the module does, what it provides, examples of how to use the classes. This is different from the comments that you often see at the beginning of a file giving the copyright and license information, which IMO should not go in the docstring (some even argue that they should disappear altogether, see eg. http://hackerboss.com/get-rid-of-templates/)

As far I know, Pylint does not have a separate code for the various place where docstrings can occur, so all you can do is disable C0111. The problem is that if you disable this at module scope, then it will be disabled everywhere in the module (i.e you won't get any C line for missing function / class / method docstring. Which arguably is not nice, and you may want to add an issue for this on the pylint tracker

So what I suggest is adding that small missing docstring, saying something like:

"""
high level support for doing this and that.
"""

Soon enough, you'll be finding useful things to put in there, such as providing examples of how to use the various classes / functions of the module which do not necessarily belong to the individual docstrings of the classes / functions (such as how these interact, or something like a quick start guide).

Comments