スタッフBLOG

おはようございます。本日の当番、プログラマーのS.Kです。

ブログは研修旅行について書こうと思っていたのですが、
後日アップされるWEBレポートでの内容に被ってしまいそうなので、
毎度お馴染み(？)のプログラムの小ネタでも書こうかと思います。


今回の小ネタはDoxygen(というよりコメント)についてのお話です。

・Doxygenとは
プログラムのコメントからドキュメントを自動生成する便利ツール
※HTMLやPDF等の形式で出力が可能

基本的にプログラムにコメントを記載する目的は、
可読性を保守する為のコードの説明や意図の記述等がありますが、
Doxygenではドキュメントの生成にも使用する事が出来ます。

Doxygenの使用方法を簡単に説明すると以下の手順になります。
1.ソースコードの記述
2.ソースコードのディレクトリをDoxygenのINPUTディレクトリに設定
3.ドキュメントの出力

簡単に説明するとたったこれだけでドキュメントが作れてしまいます。

但し、ドキュメントを生成するに際に手順1で注意事項があります。
それはコメントをDoxygenの形式に合わせて記述する必要がある事です。

という訳で、Doxygenを使ったコメントの記述方法を簡単に紹介したいと思います。
Doxygenの記述の方法については複数の方法がありますので、
今回は僕が普段使用している記述で説明したいと思います。

・基本的な記述
『//! @***』と記述する事で出力したい内容を指定します。
***の部分が内容の指定部分になります。
例えば『//! @author S.K』と指定すると作成者がS.Kとして出力されます。
又、『//! ***』と指定する事で関数や変数等の説明を記述する事が出来ます。
例外等もありますが、基本はこの形式にしています。

・ソースファイルの説明(ソースの先頭に記述)
//! @file ファイル名
//! @brief 要約説明
//! @author 作成者

・関数の説明(関数の前に記述)
//! 関数説明
//! @param 引数名 [out] 引数説明
//! @param 引数名 [in] 引数説明
//! @return 戻り値説明

・クラス、変数、enum、namespace等々(それぞれの前に記述)
//! 説明文

他にも色々とありますが、基本的には上記のもので対応出来ます。

・上記を使った簡単な例
※sub.hに記述した場合
//! @file sub.h
//! @brief 減算定義
//! @author S.K

//! 減算
//! @param a [in] 減算される値
//! @param b [in] 減算する値
//! @return 減算結果
int sub(int a, int b)
{
　　return a - b;
}

とこんな感じに記述していきます。
普段は必要ないかもしれませんが、こういった記述を心がけておく事で、
引き継ぎ等があった際のドキュメント作成が楽に行えるかもしれません。

C、C++以外にも色々と対応しているので、
気になった方はDoxygenで調べてみて下さい。