ecloxとdoxygenで仕様書メンテナンスの効率をUP!:生産性向上への道 Eclipseで行うC/C++開発(4)(2/4 ページ)
仕様書メンテナンスの課題「ドキュメントとソースコードの整合性の乖離(かいり)」をecloxとdoxygenを使って解消する。
ソースコードにdoxygenコメントを追加
doxygenコメントについて
では、doxygen用のコメントを「Addition.c」に追加してみましょう! と、いきたいところですが、その前にdoxygenのコメントについて簡単に説明します(注)。
doxygenでは、ソースコードの構造を解析してドキュメントを生成する機能を提供していますが、doxygenの機能を最大限に利用するにはdoxygenコメントの書き方を把握する必要があります。
doxygenコメントには「概要記述」と「詳細記述」の2つのコメントがあります。それぞれの違いは以下のとおりです。
doxygenコメント | 説明 | 説明 |
---|---|---|
概要記述(brief description) | 詳細解説およびサマリーに利用されるコメント | 主に1行のコメントで記載 |
詳細記述(detailed description) | 詳細解説の個所のみで利用されるコメント | 複数行のコメントで記載 |
いずれのコメントもファイルの先頭、コメントの対象となる関数、構造体、C++のクラス、メンバ変数、メソッドなどの宣言や定義の前に記述します。
doxygenの出力例と概要記述、詳細記述の対応は図4のようになります。図4はdoxygenが出力するファイルの説明ドキュメントの例です。doxygenが出力するドキュメントは「サマリー」と「詳細説明」に分かれます。サマリーには概要記述で記載した内容が、詳細説明には概要記述と詳細記述で記載した内容が反映されます。サマリーにも反映させたい内容については概要記述を利用してください。
それでは、概要記述、詳細記述のコメントのスタイルについて説明します。
概要記述では以下のようなコメントスタイルでコメントを記載します。
詳細記述では、以下のようなQtスタイルやJavaDocスタイルでのコメントを記載できます。
概要記述のコメントを複数行続けて記述すると、概要記述ではなく、詳細記述として扱われ、サマリーに表示されなくなるので注意が必要です。ちょっと分かりにくいですが、以下は詳細記述と見なされます。
詳細記述中に概要記述を記載したい場合には、後述する「@brief」というセクションコマンドを利用して下記のように記載します。@briefセクションコマンドを利用すると、空のコメント行までが概要記述として扱われます。
前述のとおりdoxygenでは補足説明を付けたい変数や関数の定義前に通常コメントを記載しますが、enum型や変数などの場合は定義の後にコメントを付けるケースもあります。doxygenのコメントは、このような後方コメントにも対応しており、以下のように記述することで前の宣言を修飾できます。
また、doxygenのコメント形式の中では“スペシャルコマンド”や“HTMLコマンド”と呼ぶ記法でコメント内容に関して細かな指定が可能です。doxygenには視覚的に意味を持たせる「視覚修飾コマンド」やファイルや関数や変数の仕様に基づいた意味を説明するための「セクションコマンド」が用意されています。代表的なものを以下に解説します。
doxygenコメントの埋め込み
それでは、これまでの解説を基に前回作成したサンプルアプリケーションにdoxygenコメントを追加してみましょう。
CDTの[C/C++ プロジェクト]ビューから「sample」プロジェクトの「Addition.c」をダブルクリックし、Addition.cをC/C++のエディタで開きます。
「Addition.c」のソースコードの先頭に以下のようにdoxygenコメントを記載します(画面1)。
また、グローバル変数「globBase」にdoxygen後置コメントを記載します。
int globBase = 10; ///< 足し算用のパラメータ
次の関数にそれぞれ以下のように、パラメータと戻り値のコメントを記載します。
/** * @brief 基数を返却する * * @param obj 該当のAdditionオブジェクト * @return 基数 */
/** * @brief 基数を設定する * * @param obj 該当のAdditionオブジェクト * @param _base 基数に設定する数 */
/** * @brief 基数とパラメータの数を加算し、その結果を返却する * * @param obj 該当のAdditionオブジェクト * @param param 演算する数 * @return 演算結果 */
/** * @brief main関数 * * @param argc コマンドラインパラメータ数 * @param argv コマンドラインパラメータ * @return 関数の実行結果 * @retval 0 正常終了 * @retval 0以外 異常終了 */
最終的な「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; }
Copyright © ITmedia, Inc. All Rights Reserved.