DoxygenでPythonコードをドキュメント化するとき、嵌ったのでmemoを残しておきます。
pythonでdocstring形式のコメントは、関数にカーソル置くとVScodeの編集支援機能でコメントが表示されます。
■docstring形式コメント例
def leftCosets(self, H: FiniteGroup) -> Set[Set[GroupElement]]:
"""
@brief Calculates left cosets of H in self.
@details foo
:param H: subGroup of self
:return:
@note bar
"""
cosets = {frozenset(copy.deepcopy(H.elements)),}
remain = self.elements - H.elements
while len(remain) > 0:
#〜中略〜
return cosets
関数にカーソルをあわせるだけで、関数定義位置に移動しなくてもコメントで確認できるので便利です。
ただしdocstring形式は、「doxygenの特殊コマンドはどれもサポートされていない」ため、Doxygenでドキュメント化するときれいに表示されません。
そこで、docstring形式をdoxygen形式に変換するフィルターを使います。
■docstring形式をDoxygen形式に変換するフィルター
doxyfilter_python(GitHub)
このフィルタを使うとdocstring形式がdoxygen形式に変換されてDoxygenに渡されます。
■doxygen形式コメント例
##
#@brief Calculates left cosets of H in self.
#@details foo
#
#@param H (FiniteGroup) subGroup of self
#@return (Set[Set[GroupElement]])
#
#@note bar
def leftCosets(self, H: FiniteGroup) -> Set[Set[GroupElement]]:
cosets = {frozenset(copy.deepcopy(H.elements)),}
remain = self.elements - H.elements
while len(remain) > 0:
#〜中略〜
return cosets
※注意※Windows環境でこれをそのまま使うと、cp932で動作して日本語が文字化けしてしまいます。
Windows環境で使う場合、doxyfilter_python.pyを編集してエンコーディング”utf-8”を指定します。
import io
#〜中略〜perform_fh関数のはじめに以下の行を追加
sys.stdout = io.TextIOWrapper(sys.stdout.buffer,encoding='utf-8')
#〜中略〜main関数のファイルオープンの箇所にエンコーディングを指定。
with open(file, 'r',encoding='utf-8') as fh:
■Doxygenの設定などの注意事項
Python は、C や C++ より、見た目が Java に似ているので、設定ファイルでは OPTMIZE_OUTPUT_JAVA から YES に設定してください。
- @briefや@detailsの間は必ず1行分空けること。そうしないと VS Code のツールチップで項目が改行されずに1行になって表示されてしまう。
- 必ずファイルコメントを入れること。そうしないとグローバルメソッドがドキュメント化されない。
『VS Code の編集支援を生かしつつ Python3 で Doxygen を使う』より
- Expert タブ -> Topics -> Input -> INPUT_FILTERにdoxyfilter_python.pyをフルパスで指定してください。
参考にしたサイト（『VS Code の編集支援を生かしつつ Python3 で Doxygen を使う』）には
必ず doxyfilter_python.py をフルパスで指定し、python3 で実行するように明示すること(そうしないと失敗した)。
と書かれていていますがが、python3.x系しか入っていない環境ではpython3を明示する必要はなさそうです。