はじめに
doxygenはソフトウェアのドキュメント化を自動で行ってくれるオープンソースソフトウェアです。ソフトウェアは規模が大きくなってきて、開発メンバーが増えてくると、新しく加入するメンバーへの教育方法として、ドキュメントが非常に重要になってきますが、その一方で開発が忙しくてドキュメント化が進まない現状があります。
doxygenはそのような場合にでも、あらかじめ決まった形式でコメントを入れることにより、自動でドキュメント作成を行ってくれる優れたツールです。今回はそのdoxygenの利用方法について学んでいきたいと思います。
レッスン１．doxygenとは
まずは、doxygenとは何なのか、何ができるのかを学んでいきましょう。以下がdoxygenの概要です。
対応言語：C/C++、Java、Python、PHPなど
対応OS：Windows、Mac、Linux
doxygen公式サイトhttp://www.doxygen.jp/
doxygenでできる主な機能は以下です。
- ソースコードから構造に関するドキュメントを自動で作成できる
- UMLの出力も可能
- HTMLでオンラインドキュメント化もできるし、Wordなどの文書の出力も可能
幅広い言語と、OSに対応しているので、環境を選ばず活用することができます。
レッスン２．環境を整える
続いて、doxygenの本体を入手し、インストールを進めていきましょう。
下記のサイトにアクセスし、本体を入手します。
https://sourceforge.net/projects/doxygen/files/snapshots/
ページの中ほどに緑色のボタンがあるので、そこからダウンロードしてください。
ダウンロードしたら、exeファイルを実行します。
規約に同意したら、次に進みます。
パスは必要に応じて変更してください。通常はそのままで結構です。
ヘルプドキュメントは容量を取るので、オンラインでヘルプを見ることができる環境である場合はチェックを外して構いません。
Nextで次に進んでください。
「Intall」を押して、インストールを開始します。
インストールが完了したら、「Finish」を押してウィンドウを閉じてください。
インストールが完了したので、続いて設定を行っていきます。
ご自分でお使いのプロジェクトがあれば、そちらを使っていただいて構いませんが、今回はデモですのでサンプルコードとして、以下を準備しました。
ヘッダとCPPソースとなりますので、それぞれ拡張子を指定して、同じディレクトリに保存しておいてください。
サンプルコード(sample.hとして保存)
/**
* @def _DEBUG
* @brief デバッグモード有効化
* @details 詳細な説明がある場合にはここに書く
*/
#define _DEBUG 1
/**
* @namespace 名前空間Sample
* @brief 名前空間の説明
* @details 詳細な説明がある場合はここに書く
*/
namespace Sample{
/**
* @brief クラスの説明
* @details 詳細なクラスの説明
*/
class CSampleClass{
public:
/**
* @brief コンストラクタの説明
*/
CSampleClass(){}
/**
* @brief デストラクタの説明
*/
~CSampleClass(){}
/**
* @fn int func
* @brief 関数の簡単な関数
* @details 詳細な説明がある場合にはここに書く
*/
int func();
};
}
サンプルコード(sample.cppとして保存)
/**
* @file sample.cpp
* @brief サンプルファイル
* @author Taro
* @date 05Apr2021
* @details doxygenを説明するためのサンプルファイル
*/
#include "sample.h"
//! 変数の説明は直前に書く
int a;
/**
* @brief 与えられた2値を加算する
* @param[in] a , b
* @param[out] 合計値
* @return int 加算した合計値
* @details 詳細な説明がある場合はここに書く
*/
int sum(int a, int b) {
return a + b;
}
ファイルが準備できたら、doxygenを起動します。スタートメニューから“Doxywizard”を開きます。
ウィザードが開いたら、下記例のようにそれぞれの環境に適したファイルパスを設定してください。
次に、ソースコードの出力内容について設定します。今回のサンプルはC++ファイルとなっていますので、言語設定はそのままで結構です。必要に応じて変更ください。
ほかに、見やすさの観点からおすすめの出力設定として、出力対象の設定を少し変更しています。
設定が終わったら、「Run」というタブを開いて、出力を開始します。
処理が無事に完了したら、早速出力結果を見てみましょう。
htmlファイルがブラウザで開きますので、内容を確認してみます。Namespacesを押すと、名前空間の一覧が開きます。
そこからクラス名をクリックすると、クラスの内容の詳細を見ることができます。
次に、ファイル単位から見てみましょう。メニューバーからFilesを選ぶと、ファイルの内容から、関数一覧、変数一覧など、様々な表示ができます。
では無事に出力ができていることが確認出来たら、doxygenの出力設定を保存しておいて、また後でも簡単に出力できるよう、設定ファイルを保存しておきましょう。
先ほどの設定ウィザードに戻って、”Save as…”を選択して、設定ファイルを保存します。
後日使う場合にはこのファイルを呼び出せば、またすぐに出力できます。
レッスン３．更なる活用方法として
doxygenにはコメントのルールが定められていますが、運用する際にはこれをコーディングルールに盛り込んでしまうことをおススメします。そして、あまり使わない情報までリッチに盛り込んでしまうよりは、実際の出力を見ながら、必要となる情報を絞り込んだ上でコーディングルールを決めていくと良いと思います。
コードのドキュメント化で課題となるのは、コードが成長してもドキュメントが変更内容に追従しないことです。この点もdoxygenは解消しています。JenkinsなどのCI/CDツールと連携して、ドキュメント生成をスケジュール化しておくと、自動更新がかかって、常に最新のドキュメントを残しておくことができます。Jenkinsにはdoxygenプラグインというものが準備されているので、そちらを活用すると良いです。
おわりに
今回は自動ドキュメント生成ツールであるdoxygenを紹介しました。生成したドキュメントは、GitHub pagesなどを使って公開することが可能ですので、ソースコードとセットで管理すると良いです。実際には細かいコメントルールや、設定等がもっと豊富にあり、自由度が高いので使ってみてください。doxygenを活用してドキュメント化に割く時間を減らしましょう。最後までお読みいただきありがとうございました。
