python - 结构化的 python 文档字符串，IDE 友好

Question

在 PHP 中，我习惯了 PHPdoc 语法：

/** Do something useful
@param first    Primary data
@return int
@throws BadException
*/
function($first){ ...

— 一个简短的有用参考：当您只需要回忆“那是什么？？”时非常方便，尤其是对于 3rd 方库。此外，所有 IDE 都可以在弹出提示中显示此内容。

Python 中似乎没有约定：只是纯文本。它很好地描述了事情，但它太长了，无法作为摘要。

好吧，就这样吧。但在我的应用程序中，我不想使用成堆的明文。

是否有任何众所周知的约定可以遵循？以及如何记录类属性？！PyCharm IDE食谱特别受欢迎 :)

在 Python3 中有一个用于功能注释的PEP 3107 。这对 2.x（特别是 2.6）没有用

还有一个用于 reStructuredText 的PEP 0287：花哨但仍然没有结构化。

score 2 · Accepted Answer

我使用epydoc。它支持 reStructured Text 中的注释，并根据这些注释生成 HTML 文档（类似于 javadoc）。

score 1 · Accepted Answer

numpydoc标准定义明确，基于 reStructuredText（这是 python 生态系统中的标准），并具有 Sphinx 集成。为 PyCharm 编写一个可以消化 numpydoc 的插件应该是相对简单的。

2 回答 2