Python模块文档字符串中应包含什么内容？

Question

好的，我看过了 PEP 8 和 PEP 257，也为很多函数和类写过文档字符串，但我对模块的文档字符串应该包含什么有点不确定。我觉得至少应该记录模块里导出的函数和类，但我也见过一些模块列出作者名字、版权信息等等。有没有人能给我一个好的 Python 文档字符串应该怎么结构的例子？

Answer 1

引用一下规范：

一个脚本的文档字符串（也就是说明文字）应该能作为它的“使用”信息，当脚本被错误或缺少参数调用时（或者用“-h”选项请求“帮助”时）打印出来。这样的文档字符串应该说明脚本的功能和命令行语法、环境变量以及文件。使用信息可以相当详细（可能有好几屏的内容），应该足够让新用户正确使用这个命令，同时也能为高级用户提供所有选项和参数的快速参考。

一个模块的文档字符串通常应该列出模块导出的类、异常和函数（以及其他对象），并给出每个对象的一句话总结。（这些总结通常比对象文档字符串中的总结要简短。）一个包的文档字符串（也就是包的__init__.py模块的文档字符串）也应该列出包导出的模块和子包。

一个类的文档字符串应该总结它的行为，并列出公共方法和实例变量。如果这个类是为了被继承而设计的，并且有额外的接口供子类使用，这个接口应该单独列出（在文档字符串中）。类的构造函数应该在它的__init__方法的文档字符串中进行说明。每个方法应该有自己的文档字符串来说明。

一个函数或方法的文档字符串是一个以句号结尾的短语。它描述了函数或方法的作用，像是一个命令（“做这个”，“返回那个”），而不是简单的描述；例如，不要写“返回路径名...”。一个多行的函数或方法文档字符串应该总结它的行为，并记录它的参数、返回值、可能的副作用、引发的异常，以及调用时的限制（如果适用的话）。可选参数应该被标明。还应该说明关键字参数是否是接口的一部分。

Answer 2

想象一下，有人正在交互式解释器里输入 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)

如你所见，关于类（还有函数，虽然我这里没有展示）的详细信息已经包含在这些组件的文档字符串里；模块自己的文档字符串应该简要描述这些内容（如果有的话），而更应该集中在模块整体能为你做什么的简明总结上，最好还带有一些经过测试的示例（就像函数和类的文档字符串里理想情况下也应该有经过测试的示例一样）。

我觉得像作者名字、版权和许可证这样的元数据对模块的用户没有什么帮助——这些信息可以放在注释里，因为它们可能对考虑是否重用或修改模块的人有帮助。