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.bfg which uses this extensively (example file, documentation example).
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.
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 257 describes 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.
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
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
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.
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.
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.
发布评论
评论（7）
我同意“任何你无法从方法签名中看出的东西”。 它还可能意味着解释方法/函数返回什么。
您可能还想在文档字符串中使用 Sphinx （和 reStructuredText 语法）用于文档目的。 这样您就可以轻松地将其包含在您的文档中。 例如，查看 repoze.bfg ，它广泛使用了这个（示例文件，文档示例）。
文档字符串中可以放入的另一件事也是 doctests。 这可能有道理，尤其是。 对于模块或类文档字符串，您还可以以这种方式展示如何使用它并同时使其可测试。
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.bfg which uses this extensively (example file, documentation example).
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.
来自 PEP 8：
From PEP 8:
查看 numpy 的文档字符串以获取很好的示例（例如 http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py" com/numpy/numpy/blob/master/numpy/core/numeric.py）。
文档字符串分为几个部分，如下所示：
Check out numpy's docstrings for good examples (e.g. http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py).
The docstrings are split into several sections and look like this:
那里应该放什么：
任何你无法从方法签名中看出的东西。 在这种情况下，唯一有用的是：displayName - 如果为空将设置为字段名称。
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.
我能想到包含在文档字符串中的最引人注目的内容是那些不明显的内容。 通常这包括类型信息或功能要求 - 例如。 “需要一个类似文件的对象”。 在某些情况下，这可以从签名中明显看出，但在其他情况下则不然。
您可以放入文档字符串中的另一个有用的东西是
doctest。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.我喜欢使用文档尽可能详细地描述函数的功能，尤其是极端情况（也称为边缘情况）的行为。 理想情况下，使用该函数的程序员永远不必查看源代码 - 实际上，这意味着每当另一个程序员确实必须查看源代码以弄清楚该函数如何工作的一些细节时，该细节可能应该是文档中提到。 正如 Freddy 所说，任何不向方法签名添加任何细节的内容可能都不应该出现在文档字符串中。
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.
在函数开头添加文档字符串的一般目的是描述函数，它做什么，它会返回什么，以及有关参数的描述。 如果需要，您可以添加实施细节。 您甚至可以为未来的开发人员添加有关编写代码的作者的详细信息。
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.