好的,所以我已经阅读了PEP 8和PEP 257,并且我已经为函数和类编写了很多文档字符串,但是我对模块docstring中的内容有点不确定.我想,至少它应该记录模块导出的函数和类,但我也看到了一些列出作者姓名,版权信息等的模块.有没有人有一个好的python文档字符串如何应该的例子结构化？

解决方法:

想想有人在交互式口译员的提示下做帮助(你的模块) – 他们想知道什么？ (提取和显示信息的其他方法大致相当于信息量方面的帮助).所以如果你有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)

正如你所看到的,关于类的详细信息(以及函数,虽然我没有在这里展示)已经包含在那些组件的文档字符串中;模块自己的docstring应该非常简单地描述它们(如果有的话),而是集中精力概括整个模块可以为你做什么,理想情况下是一些经过证明的示例(就像函数和类理想情况下应该有doctested示例一样)他们的文档字符串).

我没有看到作者姓名和版权/许可等元数据如何帮助模块的用户 – 它可以更好地进行评论,因为它可以帮助有人考虑是否重用或修改模块.