DoxygenでPythonコードを文書化

　Doxygenの動作を試さず、コメントだけをそのフォーマットにしてましたが、document化したときにちょっと想定している動きと違っていることがわかりました。覚書として残しておきます。（2020/8/29 追記あり）

Doxygen
まとめ
追記(2020/8/29)

Doxygen

　これまでCでは使ってましたが、ちょっと調べた感じPythonでも使えそうだったので、ひとまず今後のコメントはこのフォーマットにしておこうと思って、コメントだけはつけてましたが、残念ながら思った動きと違いました。

　ちょっと調べた感じ、

class Hoge(object):
    """
    @class クラス名
    @brief クラスの簡単な説明
    @details クラスの詳細な説明
    @warning 警告メッセージ
    @note メモ
    """

    def __init__(self,arg):
        """
        @fn __init__()
        @brief Hogeクラスの初期化関数
        @details 関数の詳細
        @param arg argの説明
        @return None 戻り値なし
        @warning 警告メッセージ
        @note メモ
        """
        self.arg = arg

　このスタイルが紹介されてました。（この記述もそのサイトからの転記です。）確かにこれでも動きましたが、このソースから吐き出されたhtmlでうまくリスト表示されませんでした。C時代になじみのある形式に変換されませんでした。

　おかしいなぁと思って本家のサイトを調べてみたところ、

http://www.doxygen.jp/docblocks.html

　ここの「Python での特殊ドキュメント・ブロック」の項に、このスタイルの説明がありました。サポートされている形式のようですが、残念ながら、「このケースでは、doxygen の特殊コマンドはどれもサポートされないことに注意してください。」とのこと。つまり＠ｘｘの部分はただのコメントと判断されるようです。

2020/8/29追記

　どうやらこのdocstring倣いの形式もサポートされているようです。ごめんなさい。ただしコメントの開始は「”””!」で始める必要がありそうです。詳細はこちら。日本語のドキュメントの更新が追い付いていないようですね。

　これも別に間違った記述というわけではないのですが、自分の思いと少し違います。これまでこのスタイルでコメント付け続けていたので書き直しです。その書き直し方ですが、

##
# @file filename.py
# @version バージョン番号
# @author 作成者・更新者
# @date パッケージの作成日時・更新日時
# @brief 簡単な説明
# @details 詳細な説明
# @warning 警告メッセージ
# @note メモ

##
# @class クラス名
# @brief クラスの簡単な説明
# @details クラスの詳細な説明
# @warning 警告メッセージ
# @note メモ
class Hoge(object):

    ##
    # @brief Hogeクラスの初期化関数
    # @details 関数の詳細
    # @param arg argの説明
    # @return None 戻り値なし
    # @warning 警告メッセージ
    # @note メモ
    def __init__(self,arg):
        self.arg = arg

　が正解のようです。コメント開始位置もインテントを合わせる必要があります。これでdoxygen走らせてみたところうまくhtml化されました。＠ｘｘの部分も正しく判断され、Cのコードに付けてた頃のhtmlの表示になりました。

　これも覚書として、この＠以下の記述例ですが、

http://www.doxygen.jp/commands.html#cmd_intro

　ここに一覧があります。バックスラッシュで紹介されていますが、＠でも同じ効果のようです。山ほどあって困るのですが、普段使うのは、せいぜい

@file
@date
@brief
@details
@param
@return

　くらいですかね。

　もういっちょ覚書ですが、Pythonコードをコンバートする際は、OPTIMIZEのオプションをJAVAスタイルにするとよいそうです。（PYTHONスタイルは現状存在していないようです。）

　本家ドキュメントにも「Python は、C や C++ より、見た目が Java に似ているので、設定ファイルでは OPTMIZE_OUTPUT_JAVA から YES に設定してください。」とあります。

まとめ

　確かに本家のサイト、特に英語だったりすると斜め読みした感じ上記のフォーマットでもよさそうに見えてしまいます。doxygenの環境作って試せばよかったのですが、後回しにしてたのがまずかったです。

　ただ、いろいろ調べてみると、Pythonのコメントの付け方ですが、doxygenを使うのが正しいかどうか少し自信がなくなってきました。なんとなくなじみのスタイルを取ってしまいましたが、docstringというスタイルも一般的のようです。どちらが正解ということでもないのでしょうが、もう少し悩んでもよいかもしれません。

　このdocstringスタイルに沿ったのが冒頭の記述のようです。つまり、このスタイルであればどちらのフォーマットにも沿うことになるようです。悩ましいです。