そのため、Javadoc スタイルのドキュメントにはある程度慣れてきました。Python コードのさまざまな例を調べてみると、一見したところ、ドキュメンテーションには多くの情報が欠けているように見えます。
良い点: 自明なドキュメントを目にすることはめったにありません。Docstrings は通常、英語のマークアップの 1 段落以下であり、別々の行で目立つのではなく、統合されています。
悪い点: Python のダックタイピングと関連して、多くの関数が期待するパラメーターについて不明確であることがわかりました。型のヒント (ダック ヒンティング?) はありません。多くの場合、パラメーターはリストのように、文字列のように、ストリームのようにする必要があります。
もちろん、Javadoc は、Python の優れたイントロスペクション機能を持たない下位レベルの言語用に設計されています。
Python ドキュメントの標準とベスト プラクティスに関するアドバイスはありますか?
reStructuredText形式は、docstring に埋め込むことができる Python ドキュメントの必要性に応じて設計されたので、reST を学び、docstring をその形式でフォーマットすることをお勧めします。私が行ったように、reST でほぼすべてのドキュメントをフォーマットすることに気付くかもしれませんが、それは別のポイントです :-)
Python コードを具体的に文書化するためのSphinxシステムは、reST 形式の拡張セットであり、文書をレンダリングするためのビルド システムです。標準ライブラリを含む Python 自体を文書化するように設計されているため、Sphinx はソース コードの非常によく構造化された文書化を可能にします。これにより、すべて同じフォーマット システムを使用して、自動抽出と手書きの両方の包括的なドキュメント スイートを構築できます。
ソース コードから生成されたドキュメントのみが必要な場合は、 Epydocがソース コードから API ドキュメントを抽出します。それも、テキストの reST フォーマットを読み取ります。