Doxywizardをインストールし、Pythonでdoxygen形式でコメント付けしたコードがどのようにドキュメントされるかどうか確認してみました。いろいろ試した結果として、docstring形式との共存ができそうな気がしてきました。
Doxywizard
Doxywizardとは、Doxygenを使ってコードをドキュメント化するためのフロントエンドです。簡単に使えて便利なツールなので、その使い方とコメントの付け方の覚書を残しておきます。
インストール
まずはDoxywizardをインストールしてみます。インストールサイトです。
2020年8月現在、最新はdoxygen-1.8.20のようです。Windows環境でインストールを進めてみます。
ひとまず何も考えずdoxygen-1.8.20-setup.exeをダウンロードします。ところが実行すると。
かなり不吉なアラートが出ますが、心を強く詳細情報をクリックすると、
インストールはさせてくれます。実行をクリックします。するといつものインストールシールドが動き出します。
acceptして進みます。
ひとまず大した容量ではなさそうなので、すべてデフォルトのまま進めます。
インストール完了です。
使い方
実行してみます。
色々設定できるところが多くて面喰います。ひとまず最小限の設定をします。
Project name : 吐き出されるドキュメント（html）のタイトルになります。
Source code directory: ソースコードがあるディレクトリを指定します。
Destination directory: 出力先のディレクトリを指定します。
あと、Expertタブに言語を切り替えるオプションがあります。OUTPUT_LANGUAGEがあります。そこを「Japanese」にしておきます。
取り合えずこれでよいと思います。
どうやらPythonのコードはJavaスタイルが適しているそうなので、WizardタブのModeを選ぶと言語が選択できます。
Optimize for Java or C# outputとしておきます。
これをしておくと、Expaartタブ上では、
OPTIMIZE_OUTPUT_JAVAのオプションにチェックが入ります。どうやらWizardタブの設定はExpertタブの細かい内容のプリセットになっているようです。
またデフォルトではクラスの説明ドキュメントしか出してくれないので、必要に応じて、
上図の様に、Expertタブの「EXTRACT_ALL」にチェックを入れておく必要があります。
Runタブから、Run Doxygenをクリックすることでログが流れ、ドキュメントが完成します。
これで以前記事にしたようなコードはめでたくhtml化されますが、残念ながらソースコードの文字コードがSJISでは文字化けします。
ブラウザ側の文字コードを変更してもよいとは思いますが、コードの文字コードをUTF-8にしておけばなんの問題もなく日本語が表示されます。
Python Docstringでの特殊コマンド
以前までそうではなかったと思うのですが、PythonのDocstring形式でコメントを入れていても、Doxygenの「＠」で始まる特殊コマンドがサポートされているように見えます。公式ドキュメントにも日本語では以下の様に
"""@package docstring
Documentation for this module.
More details.
"""
def func():
"""Documentation for a function.
More details.
"""
pass
class PyClass:
"""Documentation for a class.
More details.
"""
def __init__(self):
"""The constructor."""
self._memVar = 0;
def PyMethod(self):
"""Documentation for a method."""
pass
この形式、すなわちdocstring形式では＠ｘｘの特殊コマンドはサポートしてないよ。##でコメント入れて使ってね。とあるように見えます。
上記は日本語のドキュメント。以下の英語の方では少し様子が違うように見えます。
表現の仕方次第ではサポートされるように読めます。頑張って翻訳すると、“””の代わりに”””!を使ってコメントを開始するか、PYTHON_DOCSTRINGオプションをNOに設定すればよさそうに読めます。
よくwizardの方を眺めると
確かにあります。このオプションの説明をよく読むと、やはり「デフォルトではdoxygenの特殊コマンドはただのテキストで出るよ。」とあります。ただ「このオプションをNOにすると特殊コマンドが使えるよ。」と読めます。
ただ昔のコードが混在するような場面で問題が起こっても困るので、基本デフォルトのYES設定のままにしておきたいです。
であれば新規で書くコードの方を工夫して回避していきます。個人的には結果として、上記のようなサンプルコードに対して、コメントを”””!で始める以下のこの形式に落ち着きました。
"""!@package module1
Documentation for this module 1 doc string style comment (どうやらピリオドまでが一文として解釈されるようだ).
ピリオドに続く文が詳細に来るようだ. 詳細にピリオドがあっても分断されないようだ.
@warning module warning
@note module memo
@date 2020/8/29
"""
def func(aaa):
"""! func brief.
func details
@param aaa input parameters. this is test.
@return none
@warning func warning
@note func memo
"""
pass
class PyClass:
"""! class brief.
class details
@warning class warning
@note class memo
"""
def __init__(self):
"""! constructor brief.
constructor details
@warning constructor warning
@note constructor memo
"""
self._memVar = 0
def PyMethod(self, aaa):
"""! method brief.
method details
@param aaa parameter
@return zero
@return one
@warning method warning
@note method memo
"""
pass
return 0, 1
この形式であれば、デフォルトのPYTHON_DOCSTRINGオプションをONのままでも、一応目論見通りのhtmlドキュメントが吐き出されたうえで、少しルールが緩いdocstringでもそれっぽく表現されるように見えます。（@detail @briefsは使わないことにします。）
またPython独自の複数の返り値も上記の様に併記すればそれっぽくドキュメント化してくれます。
凝った事をしようとすると色々競合して不具合あるかもしれませんが、ベーシックな使い方をする分にはこれで十分です。今後はこのスタイルにしていこうと思います。
docstring形式のドキュメントをhtml化するツールとしてsphinxというのがあるようです。このルールには乗っ取ってはいません。両ルールに沿ったコメントはできるのだろうか…。
コメント