什么放在python模块docstring? [关闭]

Posted

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了什么放在python模块docstring? [关闭]相关的知识,希望对你有一定的参考价值。

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

答案

想想有人在互动翻译的提示下做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)

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

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

另一答案

引用specifications

脚本(独立程序)的docstring应该可用作其“用法”消息,当使用不正确或缺少的参数(或者可能使用“-h”选项,“help”)调用脚本时打印。这样的docstring应记录脚本的功能和命令行语法,环境变量和文件。用法消息可以相当复杂(几个屏幕已满),并且应该足以让新用户正确使用该命令,以及对复杂用户的所有选项和参数的完整快速参考。

模块的docstring通常应列出模块导出的类,异常和函数(以及任何其他对象),每个对应的摘要。 (这些摘要通常比对象的docstring中的摘要行提供的细节更少。)包的docstring(即包的__init__.py模块的docstring)也应该列出包导出的模块和子包。

类的docstring应该总结其行为并列出公共方法和实例变量。如果该类要进行子类化,并且具有子类的附加接口,则应单独列出此接口(在docstring中)。类构造函数应记录在其__init__方法的docstring中。各个方法应该由他们自己的docstring记录。

函数或方法的文档字符串是以句点结尾的短语。它将函数或方法的效果规定为命令(“Do this”,“Return that”),而不是描述;例如不要写“返回路径名......”。函数或方法的multiline-docstring应该总结其行为并记录其参数,返回值,副作用,引发的异常以及何时可以调用它们的限制(如果适用,则全部)。应指出可选参数。应记录关键字参数是否是接口的一部分。

以上是关于什么放在python模块docstring? [关闭]的主要内容,如果未能解决你的问题,请参考以下文章

python代码docstring生成文档之sphinx

导入内部函数是pythonic吗?

如何在Spyder中更改默认模块docstring?

Python docstring类型注释-一个类,而不是一个实例?

python代码PEP8规范示例

简明Python docstrings