Doxygenは、C/C++やJava、Pythonなどソースコードをドキュメント化するツールです。ソースコードに規定された形式でコメントを記述することで、HTMLやLaTeX、RTFファイルを生成してくれます。これによりソースコードとドキュメントの一貫性を保ことが容易になります。
Doxygenとは
たとえばソースコードに下記のようなコメントを残すことで、
/** ----------------------------------------------------------------------------
* @brief Base64エンコード
*
* @param [in] bin : バイナリーデータ
* @param bin_size : バイナリーデータ長
* @param [out] ascii : ASCIIデータ
* @return ASCIIデータ長
*/
int32_t base64_encode(const uint8_t bin[], uint32_t bin_size, uint8_t ascii[])
{
...
}下図のようなHTMLファイルを作成できるのがDoxygenです。ファイル一覧、変数一覧、関数一覧などを確認できます。
実際のところ、Doxygenにはそれほどソースコードの維持・管理に役立つような効果はありません。しかしDoxygenのルールに倣うことで、皆が統一したルールにしたがってコメントを記述できるようになる効果は期待できます。
ソースコードだけでなく、コメントの書き方も人それぞれです。それを誰かの記述一本に揃えようとすると揉めるかもしれません。しかしこういった第三者機関やオープンソースなど、ある程度知名度のあるルールにしたがうとなれば揉めにくいかもしれません。
必要なもの
- Doxygen
-
Doxygen本体です。ダウンロードからインストールまで特に悩まず進めます。
あわせて読みたいDoxygen homepage Source code documentation and analysis tool - Graphviz
-
関係図を描画するために使用します。ダウンロードからインストールまで特に悩まず進めます。
GraphvizGraphviz Please join the Graphviz forum to ask questions and discuss Graphviz. What is Graphviz? Graphviz is open source graph visualization software. Graph visualizatio…
Doxygenの推奨設定
Doxygenは英語版しかなく、また設定項目が多くてよくわからないため、おすすめの設定を紹介します。
Wizard設定
①～③はフォルダー設定です。
①project
├ ②src：ソースファイルのあるフォルダー
└ ③doxygen：生成したファイルを保存するフォルダー(※1)
④プロジェクト名を入力します。
⑤サブフォルダーのファイルもドキュメントの生成対象にします。
- パスに全角文字があると、ドキュメント生成が上手くいきません。
②LaTeX出力は不要なのでチェックを外します。
Expert設定
②関係図を描画する際は、Graphvizへのパスを設定します。
CSS設定
Doxygenの生成するHTMLは少し見づらいので、自分用にCSSをカスタムしています。その設定内容を紹介します。
CSS
本例は「doxygen.css」を直接触るのではなく、追加でCSSファイルを作成して登録します。元々のデザインが悪いわけではないので、主には下記の点を少し修正したぐらいです。
- 大きすぎる文字を小さくする。
- 小さすぎる文字を大きくする。
- 英数字のフォントをConsolasにする。
[mystyle.css]
body, table, div, p, dl {
font-family: Consolas, 'Meiryo UI', monospace;
font-size: 98%;
}
/* プロジェクト名 */
#projectname {
font-size: 200%;
}
/* 左のツリー構造のナビ */
#nav-tree .label {
font-family: Consolas, 'Meiryo UI', monospace;
font-size: 100%;
}
/* ページタイトル */
.title {
font-family: Consolas, 'Meiryo UI', monospace;
font-size: 160%;
font-weight: normal;
}
h1 {
border-bottom: 1px solid #879ECB;
color: #354C7B;
font-size: 140%;
font-weight: normal;
margin-top: 40px;
padding-bottom: 4px;
}
h2.memtitle {
font-family: Consolas, 'Meiryo UI', monospace;
font-size: 120%;
line-height: 100%;
}
/* 目次 */
div.toc h3 {
font-family: Consolas, 'Meiryo UI', monospace;
font-size: 100%;
line-height: 100%;
}
div.toc li {
font-family: Consolas, 'Meiryo UI', monospace;
font-size: 100%;
line-height: 100%;
}
/* 本文 */
.textblock {
line-height: 150%;
}
table.directory {
font-family: Consolas, 'Meiryo UI', monospace;
}
div.summary {
font-size: 100%;
}
/* 関数プロトコル */
.memproto {
padding: 2px;
}
/* ソースコード */
div.line {
font-family: Consolas, 'Meiryo UI', monospace;
font-size: 100%;
line-height: 120%;
}
/* 引数・戻り値 */
.params, .retval, .exception, .tparams {
font-family: Consolas, 'Meiryo UI', monospace;
}
/* include */
code {
font-family: Consolas, 'Meiryo UI', monospace;
}
/* extern */
span.mlabel {
font-size: 90%;
}
/* 表示階層 */
.directory .levels {
font-size: 100%;
}DoxygenにCSSを設定する
作成したCSSを、HTML_EXTRA_STYLESHEETに登録すると反映されます。
Doxygenコメントの記入例
よく使うコマンド
Doxygenには数多くのコマンドがあります。しかしこれらすべてのコマンドを覚える必要はありません。コメントを記入するために時間を取られていては本末転倒です。ここでは最低限、覚えておくと便利なコマンドを紹介します。
- @brief {概要}
-
関数や変数などの概要を記入します。基本的には1文で表せられる程度に抑えると良いでしょう。
- @details {詳細}
-
概要で記載しきれない補足説明を記載します。コメントを途中で改行したい場合は、「@n」コマンドを挿入してください。
- @file {ファイル名}
-
コメントを記載しているファイルの名前を入力します。
- @n
-
本コマンドを入れた地点でコメントを改行します。HTMLで「<br>」を入れるのと同意です。
- @param [入出力] {引数名} {引数の説明}
-
関数の引数に関する情報を記入します。[入出力]枠は省略することもできますが、[in]で入力、[in,out]で入出力、[out]で出力引数であることを明示的に表します。
- @return {戻り値の説明}
-
関数の戻り値がどういった内容のものかを表します。戻り値で関数の成否を表すような場合は、「@retval」コマンドを使用します。
- @retval {戻り値} {戻り値の詳細}
-
関数の戻り値で成否を表すような場合に使用します。
より詳細なコメントを調べたいときは、下記のウェブサイトが参考になります。
ファイルのコメント例
/**
* @file file.c
* @brief ファイルの説明
* @details 詳細説明を書くとき
*/関数のコメント例
/**
* @brief 文字列のコピー
* @details s1にs2の文字列をn文字コピーする @n
* s2の長さがnより少ない場合、残りを'\0'で埋める
*
* @param [out] s1 : 複写先の文字列型配列
* @param [in] s2 : 複写する文字列
* @param n : 複写文字数
* @return s1 (複写後の文字列)
*/
char *strncpy(char *s1, const char *s2, size_t n) {
...
}
/**
* @brief 文字列の比較
* @details '\0'以降の比較は行いません
*
* @param [in] s1 : 比較文字列1
* @param [in] s2 : 比較文字列2
* @param n : 比較文字数
* @return 比較結果
* @retval 0 : 一致
* @retval 正の値 : s1 > s2
* @retval 負の値 : s1 < s2
*/
int strncmp(const char *s1, const char *s2, size_t n) {
...
}変数のコメント例
独立した行にコメントを記入する際と、文末にコメント記入際は記載方法が変わるので注意してください。
//! ファイル名
char g_file_name[FILE_NAME_MAX];
char g_file_name[FILE_NAME_MAX]; //!< ファイル名
//! @brief ファイル名
//! @details 半角英数字のみ
char g_file_name[FILE_NAME_MAX];その他のコメント
「@todo」や「@bug」コマンドを使用すると、HTML化したときにリスト表示されます。
//! @todo 以降の処理はあとで書く
//! @bug 〇〇のときの挙動がおかしいその他…
Doxygenタグのある記事には、Doxygenコメントのサンプルがあります。それらも参考にしてください。
Doxygenの実行
下図①のボタンをクリックすることで、Doxygenのドキュメントを生成します。そのあと②のボタンをクリックすると、生成したドキュメントを表示します。
Doxygenの実行結果
Doxygenの生成ファイルを開くと、下図のような画面が表示されます。データ構造やファイルリンクをクリックすることで、ドキュメント化した内容を確認できます。
ここで上図の赤枠部が空欄になっていますが、専用のdoxファイルを作成することで簡単な説明書きなどを掲載することができます。このdoxファイルにもDoxygenのコマンドが適用されます。「Doxygenコメントの記入例」を参考に作成してください。以下はそのサンプルです。
[mainpage.dox]
/**
@mainpage My Projectの詳細
[TOC]
@section はじめに
Doxygenのメインページに自由に文章を並べることができます。 @n
文章はDoxygenのコメントルールにしたがう必要があります。 @n
Doxygenのコメントについては[{こちら}](https://cercopes-z.com/Doxygen/list-command-dxy.html)が参考になります。
@section 使用上の注意
@li リスト1
@li リスト2
@li リスト3
@attention
注意点を特別強調して記載することもできます。
@todo
やり残したことがあれば、ToDoとして記載しておきましょう。
*/作成したdoxファイルをINPUTに登録して実行することで、トップページにコメントを表示することができます。
コメント