What to put in a python module docstring?

Question

Ok, so I've read both PEP 8 and PEP 257, and I've written lots of docstrings for functions and classes, but I'm a little unsure about what should go in a module docstring. I figured, at a minimum, it should document the functions and classes that the module exports, but I've also seen a few modules that list author names, copyright information, etc. Does anyone have an example of how a good python docstring should be structured?

score 250 · Accepted Answer · edited Mar 26 '19 at 08:06

250

Think about somebody doing help(yourmodule) at the interactive interpreter's prompt — what do they want to know? (Other methods of extracting and displaying the information are roughly equivalent to help in terms of amount of information). So if you have in x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

then:

>>> import x; help(x)

shows:

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

As you see, the detailed information on the classes (and functions too, though I'm not showing one here) is already included from those components' docstrings; the module's own docstring should describe them very summarily (if at all) and rather concentrate on a concise summary of what the module as a whole can do for you, ideally with some doctested examples (just like functions and classes ideally should have doctested examples in their docstrings).

I don't see how metadata such as author name and copyright / license helps the module's user — it can rather go in comments, since it could help somebody considering whether or not to reuse or modify the module.

edited Mar 26 '19 at 08:06

answered Mar 31 '10 at 23:28

Alex Martelli

854,459
170
1,222
1,395

1

So, is it customary to include author, copyright, etc. in comments at the top of a module? – Apr 01 '10 at 00:16
2

@007brendan, it's pretty common practice, yes. – Alex Martelli Apr 01 '10 at 00:41
4

@IfLoop I doubt that there are more users who use the `help()` method in the interpreter than users who simply read the code. – confused00 Dec 18 '14 at 11:24
8

Bear in mind, the most important thing to document is *why*. Documenting what something does is the job of well written code. Documenting why is the job of documentation. – Erik Aronesty Sep 03 '19 at 12:45
1

@ErikAronesty I'm not sure I quite understand what "documenting why" means. Would you have any documentation explaining the concept and examples of such practices? – usernumber Oct 09 '20 at 08:57
@ErikAronesty That's an advice for inline code comments, not for function and module documentation. Doesn't matter how well written your code is, I don't want to read 1000 lines to figure the high-level "what is this". – Keto Jan 10 '22 at 23:48
1

what do you write in the docstring inside __init__.py and __main__.py? – PirateApp Aug 08 '22 at 03:44

score 64 · Answer 2 · edited Feb 01 '14 at 15:08

To quote the specifications:

The docstring of a script (a stand-alone program) should be usable as its "usage" message, printed when the script is invoked with incorrect or missing arguments (or perhaps with a "-h" option, for "help"). Such a docstring should document the script's function and command line syntax, environment variables, and files. Usage messages can be fairly elaborate (several screens full) and should be sufficient for a new user to use the command properly, as well as a complete quick reference to all options and arguments for the sophisticated user.

The docstring for a module should generally list the classes, exceptions and functions (and any other objects) that are exported by the module, with a one-line summary of each. (These summaries generally give less detail than the summary line in the object's docstring.) The docstring for a package (i.e., the docstring of the package's __init__.py module) should also list the modules and subpackages exported by the package.

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.

The docstring of a function or method is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...". A multiline-docstring for a function or method should summarize its behavior and document its arguments, return value(s), side effects, exceptions raised, and restrictions on when it can be called (all if applicable). Optional arguments should be indicated. It should be documented whether keyword arguments are part of the interface.

What to put in a python module docstring?

2 Answers2

Linked

Related