想象一下有人在交互式解释器的提示下提供帮助(你的模块)——他们想知道什么?(就信息量而言，其他提取和显示信息的方法大致相当于提供帮助)。如果你在x.py中

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

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

然后:

>>> import x; help(x)

显示:

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)

如您所见，这些组件的文档字符串中已经包含了关于类(以及函数，不过这里没有显示)的详细信息;模块自己的文档字符串应该非常概括地描述它们(如果有的话)，而不是集中在模块作为一个整体可以为您做什么的简明总结上，最好是一些经过文档测试的示例(就像函数和类理想情况下应该在它们的文档字符串中有经过文档测试的示例)。

我不知道像作者名字和版权/许可这样的元数据对模块的用户有什么帮助——它可以放在注释中，因为它可以帮助人们考虑是否重用或修改模块。

引用规格:

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.