如何写出有意义的文档字符串？

Question

什么,在您看来是一个有意义的文档？你期望在那里描述什么？

例如,考虑这个Python类__init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

你觉得这有意义吗？发布您的好/坏示例供所有人知道(以及一般答案,以便可以接受).

Answer 1

我同意"你从方法的签名中无法分辨的任何东西".它也可能意味着解释方法/函数返回的内容.

您可能还希望在文档字符串中使用Sphinx(和reStructuredText语法)进行文档编制.这样您就可以轻松地将其包含在文档中.有关示例,请查看例如repoze.bfg,它广泛使用(示例文件,文档示例).

人们可以在文档字符串中添加的另一件事也是doctests.这可能是有道理的.对于模块或类文档字符串,您还可以显示如何使用它并同时具有此可测试性.

Answer 2

从PEP 8:

编写好的文档字符串(又名"docstrings")的约定在PEP 257中是永生的.

• 为所有公共模块,函数,类和方法编写文档字符串.对于非公共方法,文档字符串不是必需的,但是您应该有一个注释来描述该方法的作用.此评论应出现在"def"行之后.
• PEP 257描述了良好的文档字符串约定.请注意,最重要的是,结束多行文档字符串的"""应该在一行上,并且最好以空行开头.
• 对于一个班轮文档字符串,可以将结束""保持在同一行.

Answer 3

该怎么做:

你从方法的签名中无法分辨的任何东西.在这种情况下,唯一有用的是:displayName - 如果为空将设置为字段名称.

Answer 4

查看numpy的docstrings以获得很好的例子(例如http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).

文档字符串分为几个部分,如下所示:

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents