前回の記事で、インストールと設定、作成の流れが終わりました。
次に、Doxygen形式のコメントについて解説していきます。
おおまかな流れ
Doxygenはコメントに書き込まれた特殊コマンド（@から始まる特殊な文字）を読み取って、独自のルールでドキュメント化していきます。
ルール的にはコマンドの後ろに半角スペースをいれて文章を書き込むのがメインとなります。
# @コマンド 表示させる文章
という形で書いていきます。
注意点として、#と@がくっついていると正しく動作しなかったので、私は、#と@の間はTabキーでインデントさせて空けています。（できあがるドキュメントに差はありません）また、コメントに空白行があると1つのカタマリと認識してくれないので、コメントはまとめて書いてください。たとえば、
以下のように@briefと@authorの間に空白改行があると@briefまでしか認識しなくなりました。
# @brief briefにはpackageのくわしい説明をかけます（詳細ではここが表示されます
# @author packageの作者：私です。やめてください死んでしまいます。^o^
パッケージ（ファイル）の詳細説明について
pythonパッケージ（ファイル自身）についての説明を、ソースコードファイルトップに書いておくと良いと思います。ここで生成されるドキュメントはこのファイルに存在するクラスやグローバル変数を一覧で確認することができるものになります。
サンプル
## @package Test packageのご説明（一覧で表示されるときはここが表示されます。） # @brief briefにはpackageのくわしい説明をかけます（詳細ではここが表示されます # @author packageの作者：私です。やめてください死んでしまいます。^o^ # @date packageの日付はここ。2018.04.24 # @version packageのバージョンはここ1.1
生成されたページはこちら
@briefは、クラスや変数、関数も含め、たいがいのものに付与できるオプションで、詳細説明を意味します。一覧ページからは見えませんが、More...を押したときに表示されるものになります。
グローバル変数の詳細説明について
グローバル変数のドキュメント化のしかたです。
以下のようになります。
## グローバル変数のごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief 詳細説明とか。（クリックした先のページではここが表示されます） PROGRAMFILES_PATH = "C:/Program Files (x86)" # @cond ## ドキュメント化したくないもの。\n # cond～endcondで囲むとドキュメント化されないです。 IGNORE_PATH = "C:/Program Files" # @endcond
## の二重になっているところが見出しで、
@briefは説明ですね
@cond~@endcond
こちらで挟まれたコメントや変数はドキュメント化するときに無視されます。
あまり使いません。基本的にはパブリックなものはすべてドキュメント化するのが吉です。
公式リファレンスはこちら
上記、パッケージページから確認すると以下のようになります。
クラスの詳細説明について
続いて、クラスのドキュメント化のしかたです。
まず、クラス宣言は以下。
## クラスのごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief 詳細説明とか。（クリックした先のページではここが表示されます） class SugoiClass():
とくに解説することはないですね
クラス内部の変数
## ごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief 詳細説明とか。（クリックした先のページではここが表示されます）\n # @brief Doxygenでは、改行は￥ｎで可能。 hogeHogePub = "Publicyade" ## クラスのプライベートな変数 # @brief 使い方とか。doxywizard側であえて設定しない限りプライベート変数はドキュメント化されないです __hogeHogePri = "Privateyade"
改行は\nです。
デフォルトでは、プライベート変数や関数は原則ドキュメント化されないように設定されています。原則必要ないのですが、Doxywizard上のEXTRACT_PRIVATE値を変更することであえて出力させることもできます。
結果は以下です。
クラスの各種メソッドの書き方の例
まず、引数も戻り値もないメソッドの場合
以下です。
## ごく簡単な説明（一覧で表示されるときはここが表示されます。）
# @brief くわしい説明とかいれます（メソッド詳細では表示されます。）\n
# @brief 引数の戻り値もない。シンプルなメソッドの例
def ShoboiKansu(self):
print "-ShoboiKansu-"
とくに難しいことはありません。
@briefを二個ならべて詳細説明を二行にしているだけです。
次に、
1つの引数と戻り値のあるメソッド
です。
## ごく簡単な説明（一覧で表示されるときはここが表示されます。）
# @brief くわしい説明とかいれます（メソッド詳細では表示されます。）\n
# @brief 引数と戻り値があるシンプルなメソッドの例
# @param arg 引数の説明
# @return ret_value 戻り値の説明
def Kansu(self, arg):
print "-Kansu-"
print arg
ret_value = 15
return ret_value
@paramでひとつの引数についての説明を書くことができます。
@return で、ひとつの戻り値について説明を書くことができます。
次は、
複数の引数と複数の戻り値がある複雑なメソッド
です。
## ちょっと複雑な例です # @brief くわしい説明 # @param Int_arg 引数の説明 # @param String_arg さらに引数の説明 # @warning 注意文をさしこむ場合(多用すると見づらくなるので注意) # @brief warningのくわしい説明は、こう書きます（もう一個warning書いてもＯＫ） # @retval ret_int 複数の値が返るときはreturn ではなく retvalで複数併記できます # @retval ret_String 複数の値が（ry # @note ret_Stringについて、warningほどではないけど注意することを書き込みます。 # @test サンプルコードなどを説明に埋め込みたいときに code ～ endcode使うと良いです # @code # # #使い方とかコードサンプルぅ # self.SugoiKansu() # # @endcode def SugoiKansu(self, Int_arg, String_arg): print "-SugoiKansu-" print Int_arg print String_arg ret_int = 15 ret_String "返す" #タプルで複数値を返す return ret_int, ret_String
@retval こちらは、@returnとちがって複数の戻り値を分けて書くことができます。@returnを複数行かいても、1つにまとめられてしまうためこれを使っています。
@warning これは、注意を表す赤いマークをつけるオプションです。任意のところに書き足すことができますが、多用すると読みにくくなるので注意です。
@note これも、warningほどではないですが、メモ的なことをかいておくと見やすくなると思います。
@code～@endcode これは、使い方などのサンプルコードを埋め込むのに使えます。
コード全体
以下に、今回のサンプルのコード全体をアップしておきます。
## @package Test packageのご説明（一覧で表示されるときはここが表示されます。） # @brief briefにはpackageのくわしい説明をかけます（詳細ではここが表示されます # @author packageの作者：私です。やめてください死んでしまいます。^o^ # @date packageの日付はここ。2018.04.24 # @version packageのバージョンはここ1.1 ## グローバル変数のごく簡単な説明（一覧で表示されるときはここが表示されます。） # 詳細説明とか。（クリックした先のページではここが表示されます） PROGRAMFILES_PATH = "C:/Program Files (x86)" # @cond ## ドキュメント化したくないもの。\n # cond～endcondで囲むとドキュメント化されないです。 IGNORE_PATH = "C:/Program Files" # @endcond ## クラスのごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief 詳細説明とか。（クリックした先のページではここが表示されます） class SugoiClass(): ## ごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief 詳細説明とか。（クリックした先のページではここが表示されます）\n # @brief Doxygenでは、改行は￥ｎで可能。 hogeHogePub = "Publicyade" ## クラスのプライベートな変数 # @brief 使い方とか。doxywizard側であえて設定しない限りプライベート変数はドキュメント化されないです __hogeHogePri = "Privateyade" ## ごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief プライベートメソッドっぽいけど、コンストラクタ、こいつはドキュメント化されます。 def __init__(self): print "-INIT-" ## ごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief くわしい説明とかいれます（メソッド詳細では表示されます。）\n # @brief 引数の戻り値もない。シンプルなメソッドの例 def ShoboiKansu(self): print "-ShoboiKansu-" ## ごく簡単な説明（一覧で表示されるときはここが表示されます。） # @brief くわしい説明とかいれます（メソッド詳細では表示されます。）\n # @brief 引数と戻り値があるシンプルなメソッドの例 # @param arg 引数の説明 # @return ret_value 戻り値の説明 def Kansu(self, arg): print "-Kansu-" print arg ret_value = 15 return ret_value ## ごく簡単な説明 # @brief プライベートメソッドなのではドキュメント化されません def __Private_Kansu(self): print "-Private_Kansu-" ## ちょっと複雑な例です # @brief くわしい説明 # @param Int_arg 引数の説明 # @param String_arg さらに引数の説明 # @warning 注意文をさしこむ場合(多用すると見づらくなるので注意) # @brief warningのくわしい説明は、こう書きます（もう一個warning書いてもＯＫ） # @retval ret_int 複数の値が返るときはreturn ではなく retvalで複数併記できます # @retval ret_String 複数の値が（ry # @note ret_Stringについて、warningほどではないけど注意することを書き込みます。 # @test サンプルコードなどを説明に埋め込みたいときに code ～ endcode使うと良いです # @code # # #使い方とかコードサンプルぅ # self.SugoiKansu() # # @endcode def SugoiKansu(self, Int_arg, String_arg): print "-SugoiKansu-" print Int_arg print String_arg ret_int = 15 ret_String "返す" #タプルで複数値を返す return ret_int, ret_String
参考
今回ご説明したもの以外にも数多くの特殊コマンドがサポートされています。ただし、Pythonの場合、\(バックスラッシュ）を@と読み替えてください。
上記で説明した Python流の書き方についての基本的な公式資料は以下 。（やたら短い）
www.doxygen.jp
この情報が皆様のお役にたてれば幸いです。
