在 python 模块文档字符串中放什么？ [关闭]答案

【问题标题】：What to put in a python module docstring? [closed]在 python 模块文档字符串中放什么？ [关闭]
【发布时间】：2022-12-06 12:45:49
【问题描述】：

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

【问题讨论】：

标签： python documentation module

【解决方案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)

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

我看不出像作者姓名和版权/许可这样的元数据如何帮助模块的用户——它宁愿放在 cmets 中，因为它可以帮助人们考虑是否重用或修改模块。

【讨论】：

那么，在模块顶部的cmets中是否习惯包含作者、版权等？
@007brendan，这是很常见的做法，是的。
@IfLoop 我怀疑在解释器中使用help()方法的用户比单纯阅读代码的用户多。
请记住，要记录的最重要的事情是为什么.记录某事的作用是编写良好的代码的工作。记录为什么是文档的工作。
@ErikAronesty 我不确定我是否完全理解“记录原因”的含义。您是否有任何文档来解释此类实践的概念和示例？

【解决方案2】：

引用 specifications：

的文档字符串脚本（一个独立的程序）应该可以用作它的“使用”消息，当使用不正确或丢失的参数调用脚本时打印（或者可能使用“-h”选项，用于“帮助”）。这样的文档字符串应该记录脚本的函数和命令行语法、环境变量和文件。使用信息可以相当详尽（占满几个屏幕）并且应该足以让新用户正确使用命令，以及对老练用户的所有选项和参数的完整快速参考。

的文档字符串模块通常应该列出模块导出的类、异常和函数（以及任何其他对象），每一个都有一个单行摘要。（这些摘要通常比对象的文档字符串中的摘要行提供的细节更少。）包的文档字符串（即包的__init__.py模块的文档字符串）还应该列出包导出的模块和子包。

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

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

【讨论】：