我同意任何你不能从方法的签名告诉。

您可能还需要使用 Sphinx （和reStructuredText语法），以便在docstrings中进行文档编制。这样，您可以轻松地将它包括在您的文档中。例如， repoze.bfg 广泛使用此功能（示例文件，文档示例） http://docs.python.org/library/doctest.html =nofollow noreferrer> doctests 。这可能有意义esp。对于模块或类的文档字符串，你也可以显示如何使用它，并有可测试的同时。

What, in Your opinion is a meaningful docstring? What do You expect to be described there?

For example, consider this Python class's __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).

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.