What to put in a python module docstring?
Question: Ok, so I've read both [PEP 8](http://www.python.org/dev/peps/pep-0008/) and
[PEP 257](http://www.python.org/dev/peps/pep-0257/), 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?


Answer: 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 theit
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.

