您认为什么是有意义的文档字符串？你希望在那里被描述什么？
例如，考虑这个 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
"""
你觉得这有意义吗？发布您的好/坏示例以供所有人了解（以及一般性答案，以便可以接受）。
【问题讨论】：
我同意“从方法的签名中无法分辨的任何内容”。这也可能意味着解释方法/函数返回什么。
您可能还想在您的文档字符串中使用Sphinx（和reStructuredText 语法）来记录文档。这样您就可以轻松地将其包含在您的文档中。例如，请查看例如repoze.bfg 广泛使用它（example file，documentation example）。
另一个可以放入文档字符串的东西也是doctests。这可能是有道理的，尤其是。对于模块或类文档字符串，您还可以展示如何使用它并同时使其可测试。
【讨论】：
doctests 是一个很好的建议。有意义的例子不仅可以向用户展示如何处理边缘情况，同时如果对代码的任何更改改变了预期的行为，也会向您发出警告。您还可以在每次发现错误时扩展这些示例，以确保它不会再次蔓延到您身上，或者至少在未纠正时警告该错误的存在。
【讨论】：
查看 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
【讨论】：
应该去那里：
从方法的签名中无法分辨的任何内容。在这种情况下，唯一有用的是：displayName - 如果为空，将设置为字段名称。
【讨论】：
我能想到包含在文档字符串中的最引人注目的东西是不明显的东西。通常这包括类型信息或能力要求 - 例如。 “需要一个类似文件的对象”。在某些情况下，这可以从签名中明显看出，而在其他情况下则不然。
您可以在文档字符串中添加的另一个有用的东西是doctest。
【讨论】：
我喜欢使用文档尽可能详细地描述函数的作用，尤其是在极端情况（也称为边缘情况）下的行为。理想情况下，使用该函数的程序员永远不必查看源代码 - 实际上，这意味着每当另一个程序员确实必须查看源代码以了解该函数如何工作的一些细节时，该细节可能应该是文档中提到。正如 Freddy 所说，任何不向方法签名添加任何细节的东西都可能不应该出现在文档字符串中。
【讨论】：
在函数开头添加doc string的一般目的是描述函数，它做什么，它会返回什么，以及关于参数的描述。如果需要，您可以添加实施细节。甚至您可以添加有关为未来开发人员编写代码的作者的详细信息。
【讨论】：