python 如何编写有意义的文档字符串？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/601900/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to write meaningful docstrings?
提问by Konrads
What, in Your opinion is a meaningful docstring? What do You expect to be described there?
在您看来，什么是有意义的文档字符串？你希望在那里描述什么？
For example, consider this Python class's __init__:
例如，考虑这个 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
"""
Do you find this meaningful? Post Your good/bad examples for all to know (and a general answer so it can be accepted).
你觉得这有意义吗？发布你的好/坏例子让所有人都知道（以及一个通用的答案，以便它可以被接受）。
采纳答案by MrTopf
I agree with "Anything that you can't tell from the method's signature". It might also mean to explain what a method/function returns.
我同意“您无法从方法签名中分辨出的任何内容”。这也可能意味着解释方法/函数返回的内容。
You might also want to use Sphinx(and reStructuredText syntax) for documentation purposes inside your docstrings. That way you can include this in your documentation easily. For an example check out e.g. repoze.bfgwhich uses this extensively (example file, documentation example).
您可能还想将Sphinx（和 reStructuredText 语法）用于文档字符串中的文档目的。这样您就可以轻松地将其包含在您的文档中。例如，请查看repoze.bfg，它广泛地使用了它（示例文件、文档示例）。
Another thing one can put in docstrings is also doctests. This might make sense esp. for module or class docstrings as you can also show that way how to use it and have this testable at the same time.
可以放入 docstrings 的另一件事也是doctests。这可能有意义，尤其是。对于模块或类文档字符串，因为您还可以展示如何使用它并同时进行可测试。
回答by Xolve
From PEP 8:
从PEP 8：
Conventions for writing good documentation strings (a.k.a. "docstrings") are immortalized in PEP 257.
- Write docstrings for all public modules, functions, classes, and methods. Docstrings are not necessary for non-public methods, but you should have a comment that describes what the method does. This comment should appear after the "def" line.
- PEP 257describes good docstring conventions. Note that most importantly, the """ that ends a multiline docstring should be on a line by itself, and preferably preceded by a blank line.
- For one liner docstrings, it's okay to keep the closing """ on the same line.
编写好的文档字符串（又名“文档字符串”）的约定在PEP 257中永垂不朽。
- 为所有公共模块、函数、类和方法编写文档字符串。非公共方法不需要文档字符串，但您应该有一个注释来描述该方法的作用。此注释应出现在“def”行之后。
- PEP 257描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的 """ 应该单独在一行上，并且最好在前面有一个空行。
- 对于单行文档字符串，可以将结束的 """ 保留在同一行上。
回答by Martin
Check out numpy's docstrings for good examples (e.g. http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).
查看 numpy 的文档字符串以获得好的示例（例如http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py）。
The docstrings are split into several sections and look like this:
文档字符串分为几个部分，如下所示：
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
回答by eglasius
What should go there:
应该去那里：
Anything that you can't tell from the method's signature. In this case the only bit useful is: displayName - if empty will be set to field name.
任何你不能从方法的签名中分辨出来的东西。在这种情况下，唯一有用的是： displayName - 如果为空，将设置为字段名称。
回答by sykora
The most striking things I can think of to include in a docstring are the things that aren't obvious. Usually this includes type information, or capability requirements - eg. "Requires a file-like object". In some cases this will be evident from the signature, not so in other cases.
我能想到的包含在文档字符串中的最引人注目的东西是不明显的东西。通常这包括类型信息或功能要求 - 例如。“需要一个类似文件的对象”。在某些情况下，这可以从签名中明显看出，而在其他情况下则不然。
Another useful thing you can put in to your docstrings is a doctest.
您可以放入文档字符串的另一个有用的东西是doctest.
回答by David Z
I like to use the documentation to describe in as much detail as possible what the function does, especially the behavior at corner cases (a.k.a. edge cases). Ideally, a programmer using the function should never have to look at the source code - in practice, that means that whenever another programmer does have to look at source code to figure out some detail of how the function works, that detail probably should have been mentioned in the documentation. As Freddy said, anything that doesn't add any detail to the method's signature probably shouldn't be in a documentation string.
我喜欢使用文档尽可能详细地描述函数的作用，尤其是在极端情况下（又名边缘情况）的行为。理想情况下，使用该函数的程序员永远不必查看源代码 - 实际上，这意味着每当另一个程序员必须查看源代码以找出该函数如何工作的一些细节时，该细节可能应该是文档中提到。正如 Freddy 所说，任何不向方法签名添加任何细节的内容可能都不应该出现在文档字符串中。
回答by Jayesh Vaghasiya
Generally purpose of adding adding doc string in starting of function is to describe function, what it does, what it would return, and description about parameters. You can add implementation details if required. Even you can add details about author who wrote the code for future developer.
通常在函数开头添加doc字符串的目的是描述函数，它做了什么，它会返回什么，以及关于参数的描述。如果需要，您可以添加实施细节。您甚至可以为未来的开发人员添加有关编写代码的作者的详细信息。
