在python模块docstring中放什么？[关闭]

好的，我已经阅读了PEP 8和PEP 257，并且为函数和类编写了许多文档字符串，但是我不确定模块文档字符串中应该包含什么。我认为，至少它应该记录该模块导出的功能和类，但是我也看到了一些列出作者姓名，版权信息等的模块。有没有人举过一个很好的python docstring应该怎么做的例子。有条理？

考虑一个help(yourmodule)在交互式口译员提示下做的人-他们想知道什么？（其他提取和显示信息的方法在信息量方面大致相同help）。因此，如果您有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)

如您所见，这些组件的文档字符串中已经包含了有关类的详细信息（以及函数，尽管这里没有显示）。该模块自己的文档字符串应该非常简要地描述它们（如果有的话），而应该专注于该模块作为一个整体可以为您做什么的简要概述，理想情况下是带有一些经过文档测试的示例（就像函数和类在理想情况下应该在文档中经过文档测试的示例一样）他们的文档字符串）。

我看不到诸如作者姓名和版权/许可证之类的元数据如何帮助该模块的用户-而是可以添加注释，因为它可以帮助某些人考虑是否重用或修改该模块。

引用规格：

脚本 （独立程序）的文档字符串应可用作其“使用情况”消息，在使用不正确或缺失的参数（或者可能使用“ -h”选项表示“帮助”）调用脚本时打印。这样的文档字符串应记录脚本的功能和命令行语法，环境变量和文件。使用情况消息可能非常详尽（几个屏幕已满），并且对于新用户而言，足以正确使用该命令，并且对于高级用户而言，它是对所有选项和参数的完整快速参考。

模块的文档字符串 通常应列出该模块导出的类，异常和函数（以及任何其他对象），并以每行的一行摘要显示。（这些摘要所提供的详细信息通常少于对象的文档字符串中的摘要行。）程序包的文档字符串（即，程序包__init__.py模块的文档字符串）也应列出由程序包导出的模块和子程序包。

类的文档字符串 应总结其行为，并列出公共方法和实例变量。如果该类打算被子类化，并且具有子类的附加接口，则该接口应单独列出（在文档字符串中）。类构造函数的方法应记录在文档字符串中__init__。各个方法应由自己的文档字符串记录。

函数或方法的文档字符串 是一个以句点结尾的短语。它将函数或方法的效果规定为命令（“执行此操作”，“返回该值”），而不是说明。例如，不要写“返回路径名...”。函数或方法的多行文档字符串应总结其行为并记录其自变量，返回值，副作用，引发的异常以及何时可以调用它的限制（所有这些均适用）。应该指出可选参数。应该记录关键字参数是否是接口的一部分。