结构化的Python Docstrings，IDE友好

Question

在PHP中，我习惯于phpdoc语法：

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

- 一些简短的有用参考：当您只需要回想起“那是什么？”时，非常方便，尤其是对于第三方库。另外，所有IDE都可以在弹出提示中显示。

python中似乎没有惯例：只是纯文本。它很好地描述了事物，但是要花太长时间。

好，让它成为。但是在我的应用程序中，我不想使用一堆明文。

是否有众所周知的公约要遵循？以及如何记录类属性？ pycharm iDe 食谱特别欢迎:)

---

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

还有一个 PEP 0287 对于重组文本：花哨的，但仍未结构。

Answer 1

这 numpydoc 标准定义明确，基于重组文本（这是Python生态系统中的标准），并且具有狮身人面像的整合。为Pycharm编写可以消化NumpyDoc的插件应该相对直接。

Sphinx还具有有关如何记录属性的参考文献： http://sphinx.pocoo.org/ext/autodoc.html?highlight = autoattribute

Answer 2

我用 epydoc. 。它支持重组文本中的评论，并从这些注释（类似于Javadoc）中生成HTML文档。