Python Docstring：这些docstring参数到底意味着什么？

Question

有人可以告诉我以下docstring参数之间的区别吗？

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

:rtype，:return和:returns 特别是：返回和：返回看起来非常相似，那么哪些情况可以使用？

Answer 1

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

根据链接页面:return来自Python域，:returns来自JavaScript域，它们似乎都用于同一事物（即记录函数或方法的返回值）。在实践中:returns似乎很少出现，人们想知道这是否是文档错字。

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

Answer 2

他们中没有一个是他们自己的意思。各种程序将扫描文档字符串并解释某些部分（或标记）专门用于格式化，链接等。按照惯例（从javadoc开始？），此类标记通常以{{1开头}}。除此之外，具体含义取决于解析文档字符串的程序，并且没有为应使用哪些标记定义的标准。有些程序使用:来记录函数的返回值，其他程序则使用:return。

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