Doxygenを利用したソフトウェア詳細設計書の作成

投稿日：2012/04/3

作成者：TZ

弊社ではソフトウェア詳細設計書の作成時にDoxygenによる自動生成された情報を活用しております。

これはDoxygenを用いる事で以下のメリットを得ることが期待できるためです。

コードに設計内容が埋め込まれているため、コードと設計書の乖離が軽減され保守性が向上する
コメントにDoxygenに対応したタグを埋め込むだけなので低コストで詳細設計書が作成可能である
関数の呼び出し関係や、ヘッダの依存関係図の生成、各種情報へのハイパーリンクの設置など詳細設計書としての内容も高品質である
ドキュメント生成時に引数説明の記述もれ等の問題があれば指摘されるため、単純ミスが軽減され設計書の品質が向上する
記載内容などが属人的にならずに設計書の品質が安定する

また、ソフトウェアの基本設計時にDoxygenに対応した簡素なプロトタイプのコードを作成する事で、設計の妥当性などの確認を行うことも可能であり、低コストで後工程での手直しを軽減する効果が期待できます。

Doxygenは単体でも動作可能ですが、Eclipse環境で使用する事で一層利便性が向上します。
具体的にはEcloxというプラグインをインストールする事でDoxygenの各種パラメータ設定やドキュメントの生成等の制御が可能となり、問題の個所のマークアップおよび該当コードへのジャンプが可能となります。

以下にEclipse(Indigo)での使用方法などを記載します。

EclipseへのEcloxインストール

「ヘルプ」→「新規ソフトウェアのインストール」を選択
「作業対象」へ「http://download.gna.org/eclox/update」を入力し「追加」
「名前」をEclox等として「OK」
「すべて選択」し「次へ」
インストール詳細を確認し「次へ」
ライセンスを確認し、「使用条件の条項に同意します」を選択し「完了」
ソフトウェアのインストールが完了するとセキュリティ警告がでますが「OK」
Eclipseの再起動を促されるので再起動する
「ウィンドウ」→「設定」→「Doxygen」でインストールされているDoxygenを確認する。認識されていない場合は「追加」で対象のdoxygen.exeを指定する。

Doxygenファイルの作成方法

「ファイル」→「新規作成」→「その他」
「その他」→「Doxyfile」→「次へ」
適当なDoxyfile nameを設定し「完了」

EclipseのDoxygen連携

さらにEclipseにはDoxygenコメントの入力を補助する機能があり入力コストが低減されます。

「ウィンドウ」→「設定」→「C/C++」→「エディタ」のドキュメンテーション・ツール・コメント「ワークスペース・デフォルト」で「Doxygen」を選択し「OK」
コード作成時、関数のうえのラインで「/**」を入力しリターンすると、関数の引数情報を自動で取得します

あとはプロジェクト・エクスプローラで先に作成したDoxyfileを選択し右クリックから「Build Documentation」でドキュメントが自動生成されます。