什么放在一个Python模块文档string？
好吧，我已经读了PEP 8和PEP 257 ，并且为函数和类写了大量的文档，但是我对模块docstring中的内容有些不确定。 我想，至less应该logging模块导出的函数和类，但我也看到了一些列出作者姓名，版权信息等的模块。有没有人有一个好的python文档string有条理？
在交互式解释器的提示下想想有人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)
正如你所看到的，关于类的详细信息（和函数也是，虽然我没有在这里显示）已经包含在这些组件的文档中。 模块自己的文档string应该非常概括地描述它们（如果有的话），而是集中在一个简单的总结模块作为一个整体可以为你做什么，理想情况下与一些doctested的例子（就像函数和类理想情况下应该有文档化的例子theit docstrings）。
我不明白元数据（如作者姓名和版权/许可证）如何帮助模块的用户，因为它可以帮助有人考虑是否重用或修改模块。
引用规范 ：
脚本 （独立程序）的文档string应该可以用作其“用法”消息，当脚本被调用的参数不正确或缺失时（或者可能带有“-h”选项，用于“帮助”）时，会打印该脚本。 这样的文档string应该logging脚本的function和命令行语法，环境variables和文件。 用法消息可以相当复杂（几个屏幕已满），并且应该足以让新用户正确使用该命令，并且可以完整地快速参考复杂用户的所有选项和参数。
一个模块的文档string通常应该列出模块导出的类，exception和函数（以及其他任何对象），每个模块都有一个单行的摘要。 （这些摘要通常比对象的文档string中的摘要行less细节。）包的文档string（即，包的
__init__.py模块的文档string）也应该列出由包导出的模块和子包。类的文档string应该总结其行为并列出公共方法和实例variables。 如果这个类是打算子类化的，并且有一个子类的附加接口，这个接口应该单独列出（在文档string中）。 类构造函数应该在文档string中为
__init__方法logging。 单独的方法应该由他们自己的文档string进行logging。
函数或方法的文档string是以句点结尾的短语。 它将函数或方法的效果规定为一个命令（“这样做”，“返回”），而不是描述; 例如，不要写“返回path名…”。 函数或方法的多行文档string应概括其行为并logging其参数，返回值，副作用，引发的exception，以及何时可以调用的限制（全部（如果适用））。 可选的参数应该被指出。 应该logging关键字参数是否是界面的一部分。
