python - Python Docstring：这些 docstring 参数到底是什么意思？

Question

有人可以告诉我以下文档字符串参数之间的区别吗？

:type而且:param 我已经看到两者都被用来指定方法参数的类型，但我认为它们的作用并不完全相同。其中一个用于程序员，另一个用于 IDE 或类似的东西？

:rtype,尤其是 :return:return和:returns :returns 看起来很相似，那么分别在什么情况下使用呢？

Answer 1

Sphinx 文档工具使用这些约定，该工具最初是为处理 Python 文档而设计的。然而，它的受欢迎程度导致它扩展到其他领域，在Sphinx 文档中定义为“用于描述和链接到属于一起的对象的标记集合（reStructuredText 指令和角色）”。

根据链接页面:return来自 Python 域，:returns来自 JavaScript 域，它们似乎都用于同一件事（即记录函数或方法的返回值）。在实践:returns中，人们很少会怀疑这是否是文档拼写错误。

:rtype指定返回类型，并在可能的情况下创建指向类型定义的链接（即，如果 Sphinx 可以在您正在记录的代码中找到定义）。

Answer 2

它们本身没有任何意义。各种程序将扫描文档字符串并解释某些片段（或标签），专门用于格式化、链接等。按照惯例（以javadoc? 开头），这些标签通常以:. 除此之外，具体含义取决于解析文档字符串的程序，对于应该使用哪些标签没有明确的标准。一些程序用于:return记录函数的返回值，另一些程序使用:rtype.

您问题的唯一真正答案是，请查阅您希望处理文档字符串的程序的文档。