構造化されたPython Docstrings、IDEフレンドリー

Question

PHPでは、PHPDOC構文に慣れていました。

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

- ちょっと短い便利なリファレンス：必要なのは、特にサードパーティのライブラリの場合、「それは何ですか？」を思い出すことだけです。また、すべてのIDEはこれをポップアップヒントに表示できます。

Pythonには慣習がないようです。ただのテキストだけです。それは物事をよく説明しますが、消化するには長すぎます。

わかりました、それをしましょう。しかし、私のアプリケーションでは、平文の山を使いたくありません。

従うべき有名な慣習はありますか？クラス属性を文書化する方法は？！ Pycharm IDE レシピは特に大歓迎です:)

---

python3にはaがあります PEP 3107 機能的な注釈用。それは2.x（具体的には2.6）には役に立ちません

またあります PEP 0287 constructuredTextの場合：ファンシーですが、それでも構造化されていません。

Answer 1

numpydoc 標準は明確に定義されており、再構築されたテキスト（Pythonエコシステム内の標準）に基づいており、Sphinx統合があります。 numpydocを消化できるPycharmのプラグインを書くのは比較的簡単です。

Sphinxには、属性を文書化する方法に関する参照もあります。 http://sphinx.pocoo.org/ext/autodoc.html?highlight=autoattribute

Answer 2

私が使う epydoc. 。再構築されたテキストでコメントをサポートし、それらのコメント（Javadocに似ています）からHTMLドキュメントを生成します。