ecloxとdoxygenで仕様書メンテナンスの効率をUP！：生産性向上への道 Eclipseで行うC／C++開発（4）（2/4 ページ）

仕様書メンテナンスの課題「ドキュメントとソースコードの整合性の乖離（かいり）」をecloxとdoxygenを使って解消する。

[小泉健（NEC） ，＠IT MONOist]

ソースコードにdoxygenコメントを追加

doxygenコメントについて

　では、doxygen用のコメントを「Addition.c」に追加してみましょう！ と、いきたいところですが、その前にdoxygenのコメントについて簡単に説明します（注）。

※注：詳細はdoxygenのオンラインマニュアルを参照してください。

　doxygenでは、ソースコードの構造を解析してドキュメントを生成する機能を提供していますが、doxygenの機能を最大限に利用するにはdoxygenコメントの書き方を把握する必要があります。

　doxygenコメントには「概要記述」と「詳細記述」の2つのコメントがあります。それぞれの違いは以下のとおりです。

doxygenコメント	説明	説明
概要記述（brief description）	詳細解説およびサマリーに利用されるコメント	主に1行のコメントで記載
詳細記述（detailed description）	詳細解説の個所のみで利用されるコメント	複数行のコメントで記載

　いずれのコメントもファイルの先頭、コメントの対象となる関数、構造体、C++のクラス、メンバ変数、メソッドなどの宣言や定義の前に記述します。

　doxygenの出力例と概要記述、詳細記述の対応は図4のようになります。図4はdoxygenが出力するファイルの説明ドキュメントの例です。doxygenが出力するドキュメントは「サマリー」と「詳細説明」に分かれます。サマリーには概要記述で記載した内容が、詳細説明には概要記述と詳細記述で記載した内容が反映されます。サマリーにも反映させたい内容については概要記述を利用してください。

図4　doxygenが出力するファイルの説明ドキュメントの例

　それでは、概要記述、詳細記述のコメントのスタイルについて説明します。

　概要記述では以下のようなコメントスタイルでコメントを記載します。

　詳細記述では、以下のようなQtスタイルやJavaDocスタイルでのコメントを記載できます。

　概要記述のコメントを複数行続けて記述すると、概要記述ではなく、詳細記述として扱われ、サマリーに表示されなくなるので注意が必要です。ちょっと分かりにくいですが、以下は詳細記述と見なされます。

　詳細記述中に概要記述を記載したい場合には、後述する「@brief」というセクションコマンドを利用して下記のように記載します。@briefセクションコマンドを利用すると、空のコメント行までが概要記述として扱われます。

　前述のとおりdoxygenでは補足説明を付けたい変数や関数の定義前に通常コメントを記載しますが、enum型や変数などの場合は定義の後にコメントを付けるケースもあります。doxygenのコメントは、このような後方コメントにも対応しており、以下のように記述することで前の宣言を修飾できます。

　また、doxygenのコメント形式の中では“スペシャルコマンド”や“HTMLコマンド”と呼ぶ記法でコメント内容に関して細かな指定が可能です。doxygenには視覚的に意味を持たせる「視覚修飾コマンド」やファイルや関数や変数の仕様に基づいた意味を説明するための「セクションコマンド」が用意されています。代表的なものを以下に解説します。

※注：doxygenコメント内では、\、@、<、>などの記号をコマンドとして使用するので、これらの記号を文字としてコメント内に記述するときにはコマンドとして解釈されないようにエスケープ文字を使ったスペシャルコマンドの記法か＆と;を使った記法を用いてください。

doxygenコメントの埋め込み

　それでは、これまでの解説を基に前回作成したサンプルアプリケーションにdoxygenコメントを追加してみましょう。

　CDTの［C/C++ プロジェクト］ビューから「sample」プロジェクトの「Addition.c」をダブルクリックし、Addition.cをC／C++のエディタで開きます。

　「Addition.c」のソースコードの先頭に以下のようにdoxygenコメントを記載します（画面1）。

画面1　doxygenコメントの追加

　また、グローバル変数「globBase」にdoxygen後置コメントを記載します。

int globBase = 10;  ///< 足し算用のパラメータ 

　次の関数にそれぞれ以下のように、パラメータと戻り値のコメントを記載します。

/**
 * @brief   基数を返却する
 * 
 * @param   obj 該当のAdditionオブジェクト
 * @return  基数
 */ 

getBase()

/**
 * @brief   基数を設定する
 * 
 * @param   obj 該当のAdditionオブジェクト
 * @param   _base 基数に設定する数
 */ 

setBase()

/**
 * @brief   基数とパラメータの数を加算し、その結果を返却する
 * 
 * @param   obj 該当のAdditionオブジェクト
 * @param   param 演算する数
 * @return  演算結果
 */ 

calculate()

/**
 * @brief   main関数
 * 
 * @param   argc コマンドラインパラメータ数
 * @param   argv コマンドラインパラメータ
 * @return  関数の実行結果
 * @retval  0 正常終了
 * @retval  0以外 異常終了
 */ 

main()

　最終的な「Addition.c」のソースコードは以下のようになります。

/** 
 * @file    Addition.c
 * @brief   足し算を行うサンプルプログラム
 *
 * @author  日電　太郎
 * @date    2007-11-30
 *
 */
 
#include <stdio.h>
#include "Addition.h"
 
int globBase = 10;  ///< 足し算用のパラメータ
 
/**
 * @brief   基数を返却する
 * 
 * @param   obj 該当のAdditionオブジェクト
 * @return  基数
 */
int getBase(Addition* obj){
    return obj->baseNum;
}
 
/**
 * @brief   基数を設定する
 * 
 * @param   obj 該当のAdditionオブジェクト
 * @param   _base 基数に設定する数
 */
void setBase(Addition* obj,int _base){
    obj->baseNum = _base;
}
 
/**
 * @brief   基数とパラメータの数を加算し、その結果を返却する
 * 
 * @param   obj 該当のAdditionオブジェクト
 * @param   param 演算する数
 * @return  演算結果
 */
int calculate(Addition* obj, int param){
    return obj->baseNum + param;
}
 
/**
 * @brief   main関数
 * 
 * @param   argc コマンドラインパラメータ数
 * @param   argv コマンドラインパラメータ
 * @return  関数の実行結果
 * @retval  0 正常終了
 * @retval  0以外 異常終了
 */
int main(int argc, char** argv){
    int value =0;
    Addition obj;
    setBase(&obj, globBase);
    value = calculate(&obj,5);
    printf("%d\n",value);
    return 0;
} 

Addition.c