以前の記事でDoxygenの動作を試さず、コメントだけをそのフォーマットにしてましたが、document化したときにちょっと想定している動きと違っていることがわかりました。覚書として残しておきます。
Doxygen
これまでCでは使ってましたが、ちょっと調べた感じPythonでも使えそうだったので、ひとまず今後のコメントはこのフォーマットにしておこうと思って、コメントだけはつけてましたが、残念ながら思った動きと違いました。
ちょっと調べた感じ、検索上位に
class Hoge(object):
"""
@class クラス名
@brief クラスの簡単な説明
@details クラスの詳細な説明
@warning 警告メッセージ
@note メモ
"""
def __init__(self,arg):
"""
@fn __init__()
@brief Hogeクラスの初期化関数
@param arg argの説明
@return None 戻り値なし
@details 関数の詳細
@warning 警告メッセージ
@note メモ
"""
self.arg = arg
このスタイルが紹介されてました。（この記述もそのサイトからの転記です。）確かにこれでも動きましたが、このソースから吐き出されたhtmlでうまくリスト表示されませんでした。C時代になじみのある形式に変換されませんでした。
おかしいなぁと思って本家のサイトを調べてみたところ、
ここの「Python での特殊ドキュメント・ブロック」の項に、このスタイルの説明がありました。サポートされている形式のようですが、残念ながら、「 このケースでは、doxygen の特殊コマンドはどれもサポートされないことに 注意してください。」とのこと。つまり＠ｘｘの部分はただのコメントと判断されるようです。
これも別に間違った記述というわけではないのですが、自分の思いと少し違います。これまでこのスタイルでコメント付け続けていたので書き直しです。その書き直し方ですが、
##
# @file filename.py
# @version バージョン番号
# @author 作成者・更新者
# @date パッケージの作成日時・更新日時
# @brief 簡単な説明
# @details 詳細な説明
# @warning 警告メッセージ
# @note メモ
##
# @class クラス名
# @brief クラスの簡単な説明
# @details クラスの詳細な説明
# @warning 警告メッセージ
# @note メモ
class Hoge(object):
##
# @brief Hogeクラスの初期化関数
# @param arg argの説明
# @return None 戻り値なし
# @details 関数の詳細
# @warning 警告メッセージ
# @note メモ
def __init__(self,arg):
self.arg = arg
が正解のようです。コメント開始位置もインテントを合わせる必要があります。これでdoxygen走らせてみたところうまくhtml化されました。＠ｘｘの部分も正しく判断され、Cのコードに付けてた頃のhtmlの表示になりました。
これも覚書として、この＠以下の記述例ですが、
ここに一覧があります。バックスラッシュで紹介されていますが、＠でも同じ効果のようです。山ほどあって困るのですが、普段使うのは、せいぜい
@file @date @brief @details @param @return
くらいですかね。
もういっちょ覚書ですが、Pythonコードをコンバートする際は、OPTIMIZEのオプションをJAVAスタイルにするとよいそうです。（PYTHONスタイルは現状存在していないようです。）
本家ドキュメントにも「Python は、C や C++ より、見た目が Java に似ているので、設定ファイルでは OPTMIZE_OUTPUT_JAVA から YES に設定してください。」とあります。
まとめ
確かに本家のサイト、特に英語だったりすると斜め読みした感じ上記のフォーマットでもよさそうに見えてしまいます。doxygenの環境作って試せばよかったのですが、後回しにしてたのがまずかったです。
ただ、いろいろ調べてみると、Pythonのコメントの付け方ですが、doxygenを使うのが正しいかどうか少し自信がなくなってきました。なんとなくなじみのスタイルを取ってしまいましたが、docstringというスタイルも一般的のようです。どちらが正解ということでもないのでしょうが、もう少し悩んでもよいかもしれません。
このdocstringスタイルに沿ったのが冒頭の記述のようです。つまり、このスタイルであればどちらのフォーマットにも沿うことになるようです。悩ましいです。
コメント