Eclipseとdoxygenの設定方法とは…？
プログラムのドキュメント作成がめんどくさい！
将来、ソフトウェアの保守をしていくために作るプログラムのドキュメント。
このドキュメントを作るのって、本当に大変ですよね？
普通は数日かかるプログラムのドキュメント作成ですが。
実はEclipseにdoxygenを連携させてコメントを書いておけば、自動で作ることができるんです。
本記事ではEclipseでdoxygenを使えるようにする方法をご紹介いたしますので、ぜひ参考にしてみてください。
気になるところへGO！
Eclipseでdoxygenを使うために必要な準備
まずは、Eclipseでdoxygenを使うための準備内容を確認していきましょう。
必要な準備は次の3つになります。
- Graphvizのインストール
- doxygenのインストール
- ecloxのプラグイン導入
①②のソフトのインストール方法は別の記事でご紹介していますので、そちらを参考にしてください。
ecloxのプラグインの導入に関しては、次の章でご紹介していきます。
プラグインecloxの設定方法
まずはEclipseでecloxのプラグインを設定していきます。
Eclipseを起動させてください。
起動したら次の図のように①『ヘルプ(H)』の②『Eclipseマーケットプレース(M)』をクリックしましょう。
30秒ほど待つとマーケットプレースの画面が表示されますので、次の画像の検索欄に『doxygen』と入力してください。
するとecloxというプラグインがヒットしますので、②『インストール』をクリックしましょう。
次の確認画面が表示されたら『確認(C)>』をクリックしてください。
するとライセンスのレビューに移動しますので、①の同意にチェックを入れて②『完了(F)』をクリックします。
Eclipseにdoxygenを設定する方法
ecloxの準備が完了したので、次はdoxygenの設定をしていきます。
マーケットプレースはもう使用しないので、閉じてしまってOKです。
ホームに戻ったら、次の画像のように①『ウィンドウ(W)』から②『設定(P)』をクリックしてください。
設定画面が表示されたら①『C/C++』を展開して、②『エディター』をクリックしましょう。
ドキュメント・ツール・コメントの枠にある③ワークスペース・デフォルトには『Doxygen』を設定してください。
設定が終わったら④『適用(A)』をクリックします。
続いて次の画像のように、左側の設定項目から『doxygen』を選びます。
最初からdoxygenが登録されていますが、インストールしたバージョンより古いので②『追加』をクリックします。
すると小さなウィンドウが表示されますので③『参照(B)』をクリックしてください。
そうしたら、次の画像のようにdoxygenの保存先を入力します。
doxygenのパスを入力したら『OK』をクリックしましょう。
そうすればインストールしたdoxygenが反映されますので、次の画像のようにチェックを入れて適用をクリックしてください。
doxygenの選択が終わったら、コードテンプレートを作っておきます。
設定の『C/C++』→『コード・スタイル』→①『コード・テンプレート』を選択しましょう。
②の場所のコメントを展開すると『ファイル』がありますので選択して、③『編集』をクリックしてください。
パターンの場所にDoxygenコメントのテンプレートを挿入できるようになるので、下記コードをコピペしましょう。
/**
* @file ${file_name}
* @brief ToDo
* @date ${date}
* @author ${user}
* @version 1.00 新規作成
*/
こうすることでソースファイルを作成すると、自動的にファイルの先頭部分へdoxygenコメントが入ります。
ファイル名と日付、著者は勝手に反映されますが、@breif（概要）は自分で記入が必要ですので、後日修正してください。
doxyfileの設定方法
doxygenの設定が終わったら、ドキュメントを作成するためにdoxyfileを作っていきます。
まずは①のプロジェクトをクリックした後に、右クリックをしてください。
こちらのようなメニューが表示されると思いますので、②『新規(N)』→③『その他(O)』をクリックしましょう。
すると次のような画面に移動するはずです。
①『Doxyfile』を選択して『次へ』をクリックして、②『完了(F)』を押しましょう。
するとプロジェクトの下にdoxyfileが作られるはずです。
作った①のdoxyfileをダブルクリックすると、次のような画面になります。
②のタブで『Basic』を選択して、③『追加』をクリックしましょう。
するとウィンドウが表示されるので、そこでソースフォルダ名を入力してください。
そのあとは画像と同じ場所にチェックを入れておきましょう。
Basicの設定が終わったら詳細設定をしていきます。
まずは言語の設定をするために、①『Advanced』をクリックして②の『Output Language』を探しましょう。
続いては、ドキュメント化する内容に関する設定です。
『Extract All』を見つけたら、『はい』にチェックを入れましょう。
そして『Generate Tree View』も同様に『はい』にチェックを入れます。
最後はドキュメントに図を表示する『Graphviz』のパスを登録します。
『DOT Files Directories』を選択して『追加』をクリックしましょう。
ウィンドウが表示されたら、Graphvizのパスを入力してください。
次の『Dot Path』も同様にGraphvizのパスを入力してください。
入力が終わったらdoxyfileの設定が完了です。
忘れずに『Ctrl』と『s』を同時押しして、doxyfileの内容を保存しておきましょう。
そしてEclipseを再起動させてください。
doxygenで自動でドキュメントを作る方法
Eclipseにdoxygenの設定ができたので、ドキュメントを作り方をご紹介します。
次の画像のようにドキュメントを作りたいプロジェクトをクリックしてから、右クリックをしてください。
下の方に『Build Documentation』という項目が追加されているので、それをクリックします。
コンソールにドキュメントの制作状況が表示されますので、そこに『Build finished!』と表示されればOKです。
5秒ほど待ってF5ボタンを押すと、次のように『html』フォルダができあがります。
『html』フォルダにある『index.html』を選択したあとに右クリックしましょう。
そして『次で開く』→『Webブラウザー』でドキュメントを開けば、ドキュメントの確認ができます。
doxygenで作ったドキュメント例
今回は参考例としてtest.cファイルでドキュメントを作ってみました。
htmlファイルを開くと次のような画面が表示されます。
ファイル一覧をクリックするとsrcフォルダの中にtest.cファイルがある事が確認できます。
このtest.cをクリックすれば、次の画像のようにプログラムの構造を見ることができるのです。
まず上側にはincludeしているヘッダーファイルの相関図が表示されます。
そして、その下にプログラムで使用されている構造体やマクロの説明が書かれているのです。
更に下側にスクロールすると…
関数の呼び出し関係やコメントに記載した関数の詳細説明を見ることができます。
この図からmain関数は整数を表示する関数であるprint_data関数を呼び出していることが分かるでしょう。
このようにdoxygenのコメントを書いておけば、分かりやすいドキュメントを自動で作成してくれるのです。
なお、参考ですがdoxygenのコメントのやり方はこちらの記事に記載します。（作成中）
また、ドキュメントの作成に使用したソースファイルは下記のとおりです。
/**
* @file test.c
* @brief doxygen用のサンプルファイル
* @date 2021/12/23
* @author tobitaka
* @version 1.00 新規作成
*/
#include<stdio.h>
#include<stdlib.h>
/** @brief 定数のサンプル */
#define SAMPLE 10
/**
* @brief 構造体のサンプル
*/
typedef struct DATA{
int number; /**!< 出席番号 */
}data;
/**
* @brief 整数を表示する関数
* @details 整数を引数として受け取り、printf関数に代入する
* @param number 整数
* @return EXIT_SUCCESS
* */
int print_data(int number);
int main(void) {
data tobitaka;
tobitaka.number = 5;
print_data(tobitaka.number);
print_data(tobitaka.number + SAMPLE);
return EXIT_SUCCESS;
}
int print_data(int number) {
printf("%d\n", number);
return EXIT_SUCCESS;
}
