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广泛使用此广告（example file，documentation example）。

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

Answer 2

来自PEP 8：

编写良好文档字符串的惯例（a.k.a.   “docstrings”）在PEP 257中永生。


为所有公共模块，函数，类和方法编写文档字符串。对于非公开方法，Docstrings不是必需的，但是你   应该有一个描述该方法的注释。这个   评论应出现在“def”行之后。

PEP 257描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的“”“应该在   单独行，最好在空行之前。

对于一个班轮文档字符串，可以将结束“”“保持在同一行。

Answer 3

应该去哪里：

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

Answer 4

查看numpy的文档字符串以获取良好示例（例如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

Answer 5

我能想到包含在文档字符串中的最引人注目的事情是不明显的事情。通常这包括类型信息或能力要求 - 例如。 “需要类似文件的对象”。在某些情况下，这将在签名中显而易见，而在其他情况下则不然。

您可以在文档字符串中添加的另一个有用的内容是doctest。

Answer 6

我喜欢使用文档尽可能详细地描述函数的功能，特别是角点情况下的行为（a.k.a.边缘情况）。理想情况下，使用该函数的程序员永远不必查看源代码 - 实际上，这意味着每当另一个程序员必须查看源代码以找出函数如何工作的一些细节时，该细节可能应该是在文档中提到。正如Freddy所说，任何不对方法签名添加任何细节的内容都可能不应该在文档字符串中。

Answer 7

通常在函数启动时添加添加文档字符串的目的是描述函数，它的作用，返回的内容以及参数的描述。您可以根据需要添加实施细节。即使您可以添加有关为未来开发人员编写代码的作者的详细信息。

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

7 个答案: