python - 在 python 模块文档字符串中放入什么？

Question

关闭。这个问题是 opinion-based .它目前不接受答案。

---

想要改进这个问题吗？ 更新问题，以便 editing this post 提供事实和引用来回答它.

关闭 4 年前。

社区审核了是否重新打开这个问题12个月前并关闭:

原始关闭原因未解决

Improve this question

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

Answer 1

想想有人在交互式解释器的提示下执行 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)

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

我不知道诸如作者姓名和版权/许可之类的元数据如何帮助模块的用户——它可以放在评论中，因为它可以帮助考虑是否重用或修改模块的人。