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)没有用

还有一个 PEP 0287对于 reStructuredText:花哨但仍不结构化。

Answer 1

我使用 epydoc .它支持重组文本中的注释，并根据这些注释生成 HTML 文档(类似于 javadoc)。