doxygen - ViVa! Saborigineer.

doxygen

　　　　みなさんは「doxygen」というツールをご存知でしょうか？
　　　　Javaには「Javadoc」というものがありますが、それのC/C++版とでもいえるスバラシイツールです。

　　　　ソースにdoxygenに合わせたコメントを記載しておけば、関数仕様書など作成する必要がありません。
　　　　Windows、Linux問わず使用できるので、Saborigineer的には試さずにはいられません。

doxygenのインストール

　　　　doxygenのインストールについてはネット上に既に有用な情報がありますので、
　　　　ここでの説明は省略します。

　　　　詳しくは以下のサイトで。
　　　　・http://www.doxygen.jp/
　　　　・http://www.google.co.jp/search?hl=ja&q=doxygen&btnG=Google+%E6%A4%9C%E7%B4%A2&lr=lang_ja

doxygenの設定

　　　　doxygenの設定は「Doxyfile」というファイルに記載されます。
　　　　C言語ソースファイルに対して使用する場合は、以下の項目を設定すればよいでしょう。

・	PROJECT_NAME	：	プロジェクト名
・	OUTPUT_DIRECTORY	：	doxygen実行結果の出力先
・	OUTPUT_LANGUAGE	：	言語の設定。日本語にしたいなら「Japanese」
・	OPTIMIZE_OUTPUT_FOR_C	：	C言語にあわせた出力結果にしたいので、「Yes」
・	EXTRACT_ALL	：	全て解析対象にしたいので「Yes」
・	INPUT	：	実行対象にするソースディレクトリの指定をする。
・	RECURSIVE	：	サブディレクトリも実行対象にしたいので「Yes」
・	GENERATE_HTML	：	HTML形式の出力をしたいので「Yes」
・	PREDEFINED	：	ソースコード中でifdef等を使用している場合はここに記載

doxygen ～コメントの書き方

　　　　doxygenの一般的なコメントの記載方法については公式サイト等で説明されているので、　面倒なので　省略。
　　　　ここでは、公式サイト等にはない書き方を説明します。

変数宣言やDEFINEとdoxygenコメントを同じ行に書けないの？

　　　　公式サイトでは、↓のような書き方を説明されていますが、

　　　　/**
　　　　　*　戻り値用変数
　　　　　*/
　　　　int result;

　　　　実際コーディングする際には、可読性も考慮し、↓のようにするのが一般的なのではないかと思います。

　　　　int result;　　　/* 戻り値用変数 */

　　　　で、「可読性もキープしつつ、doxygenコメントも書きたいんだけど…」という場合には
　　　　↓のようにするとOKです。

　　　　int result;　　　/**< 戻り値用変数 */

　　　　これを応用すると、構造体でも可読性を保ちつつ、doxygenコメントを書くことができます。

　　　　/**
　　　　　*  ～情報構造体
　　　　　*/
　　　　struct xxxx_info {
　　　　　　unsigned short       type;      /**< 情報種別 */
　　　　　　unsigned short       size;      /**< 情報長   */
　　　　};

doxygen ～コメントの書き方：残念な例

　　　　実際に使ってみて、思ったとおりにHTMLに出力されない等の残念なケースがありました。
　　　　ここにその一例を載せたいと思います。

構造体メンバーのコメント記述不足のため、HTMLの表示が不完全になる

　　　○残念：HTMLに表示されない

　　　　　struct　setinfo　/** @brief 設定情報用構造体定義 */　　　 ←★１
　　　　　{
　　　　　　　int　　　　　　　　　 reserve1 : 15　 ;　 ←★２
　　　　　　　int　　　　　　　　　 LISTCTL　:　1　 ;　 /**< リスト登録/削除 */
　　　　　　　int　　　　　　　　　 reserve2 : 14　 ;　 ←★２
　　　　　　　int　　　　　　　　　 DELOBJT　:　1　 ;　 /**< 削除対象 */
　　　　　　　int　　　　　　　　　 ADDOBJT　:　1　 ;　 /**< 登録対象 */
　　　　　};

　　　　◎構造体のメンバーにdoxygenコメントがついていないものがある場合（「★２」）、
　　　　　せっかく記載した「★１」の部分の説明が残念ながらHTMLでは表示されません。

　　　○OK：HTMLに表示される

　　　　　struct　setinfo　/** @brief 設定情報用構造体定義 */
　　　　　{
　　　　　　　int　　　　　　　　　 reserve1 : 15　 ;　 /**< reserved */　　←★
　　　　　　　int　　　　　　　　　 LISTCTL　:　1　 ;　 /**< リスト登録/削除 */
　　　　　　　int　　　　　　　　　 reserve2 : 14　 ;　 /**< reserved */　　←★
　　　　　　　int　　　　　　　　　 DELOBJT　:　1　 ;　 /**< 削除対象 */
　　　　　　　int　　　　　　　　　 ADDOBJT　:　1　 ;　 /**< 登録対象 */
　　　　　};

構造体一覧に簡易説明が表示されない　（「\brief」）

　　　　※最新バージョンのdoxygenでは問題ないかも。

　　　○残念：簡易説明が表示されない

　　　　/**
　　　　 *　受信データ待ち合わせ状態設定構造体　　　←★
　　　　 */
　　　　struct xxx_cnt {
　　　　　　uint_t　rcv_cnt;　　　　/**< 受信個数 */
　　　　　　uint_t　xxx_stat[3];　　/**< 状態 (0:受信未 1:受信済 2:受信待) */
　　　　};

　　　　◎「★」部分のdoxygenコメントで属性を指定していないため、
　　　　　せっかく記載した「★１」の部分の説明が残念ながらdoxygenでは表示されません。

　　　　　　HTMLでの表示例

　　　　　　---
　　　　　　データ構造 
　　　　　　struct　 xxx_cnt 
　　　　　　struct　 xxx_read 
　　　　　　struct　 xxx_softc 
　　　　　　struct　 xxx_chain 
　　　　　　…
　　　　　　---

　　　○OK：簡易説明が表示されない

　　　　/**
　　　　 *　\brief 受信データ待ち合わせ状態設定構造体　　　 ←★
　　　　 */
　　　　struct xxx_cnt {
　　　　　　uint_t　rcv_cnt;　　　　/**< 受信個数 */
　　　　　　uint_t　xxx_stat[3];　　/**< 状態 (0:受信未 1:受信済 2:受信待) */
　　　　};

　　　　　　HTMLでの表示例（★部分が表示される）

　　　　　　---
　　　　　　データ構造 
　　　　　　struct　 xxx_cnt 
　　　　　　　受信データ待ち合わせ状態設定構造体 [詳細]　←★
　　　　　　struct　 xxx_read 
　　　　　　struct　 xxx_softc 
　　　　　　struct　 xxx_chain 
　　　　　　…
　　　　　　---

---