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

User · Answer

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

User · 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    gt  gt  gt  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      lt dictproxy object gt              dictionary for instance variables  if defined                     weakref      lt attribute    weakref    of  Blah  objects gt              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

[python] What to put in a python module docstring?

Examples related to python

Examples related to documentation

Examples related to module