您认为什么是有意义的文档字符串?你希望在那里被描述什么?
例如,考虑这个 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 .这可能是有道理的,尤其是。对于模块或类文档字符串,您还可以展示如何使用它并同时使其可测试。
关于python - 如何编写有意义的文档字符串?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/601900/