如何编写有意义的文档？

什么，在你看来是一个有意义的文档字符串？你期望在那里描述什么？如何编写有意义的文档？

例如，考虑这个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 
    """

，你觉得这个有意义？发布你所有人都知道的好/坏例子（以及一般的答案，以便它可以被接受）。

来源

2009-03-02 Konrads

我同意“从方法签名中无法分辨的任何内容”。它也可能意味着解释什么是方法/函数返回。

您可能还想在文档字符串中使用Sphinx（和reStructuredText语法）作为文档目的。这样你可以很容易地将它包含在你的文档中。例如，查看例如repoze.bfg它广泛使用（example file,documentation example）。

另一件事可以放在docstrings也是doctests。这可能是有意义的。对于模块或类文档，您也可以通过这种方式显示如何使用它并同时具有此可测试性。

来源

2009-03-02 11:25:15 MrTopf

+1：使用带有epydoc或sphinx的RST符号。 – 2009-03-02 13:43:35

什么应该去那里：

任何你从方法的签名不能告诉。在这种情况下，唯一有用的是：displayName - 如果空将被设置为字段名称。

来源

2009-03-02 10:44:16 eglasius

+1“你从方法签名中无法分辨出来的任何东西” – 2009-03-02 10:59:08

应该去那里的特定信息在epydoc和sphinx项目中。请参阅http://epydoc.sourceforge.net/epydoc.html – 2009-03-02 13:44:44

我喜欢用文档来尽可能详细地描述函数的功能，特别是在角落案例（又名边缘案例）中的行为。理想情况下，使用该函数的程序员不应该看源代码 - 实际上，这意味着每当另一个程序员必须查看源代码以找出函数的一些细节时，该细节可能应该已经在文档中提到。正如弗雷迪所说，任何不会在方法签名中添加任何细节的东西都可能不在文档字符串中。

来源

2009-03-02 11:06:44

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

另一个有用的东西，你可以把你的文档是doctest。

来源

2009-03-02 12:34:34 sykora

从PEP 8：

约定编写好的文档字符串（又名 “文档字符串”）的永生PEP 257。

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

PEP 257描述良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的“”“应该在行上，最好在前面加一个空行。

对于一个衬垫文档字符串，它的好，以保持关闭“””在同一条线上。

来源

2009-03-02 12:51:32 Xolve

退房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

来源

2011-01-14 10:56:25 Martin

一般在功能启动添加添加文档字符串的目的是描述的功能，它做什么，世界卫生大会它会返回，并描述参数。如果需要，您可以添加实施细节。即使您可以添加有关为未来开发人员编写代码的作者的详细信息。

来源

2017-02-24 17:05:20

如何编写有意义的文档？

回答

相关问题