Doxygen ドキュメント生成ツール "概要編"

Doxygen公式サイト大体のプログラミング言語はソースコードの中に覚書としてコメントを書くことができます. Doxygenはこれらコメントを抽出して,HTMLやLaTeXのようなドキュメントへとまとめてくれる便利なツールです. コメントはDoxygen特有のルールに従って書くことで,より細かな表現もできるようになります. 特有のルールと言ってもその書式はLaTeXに似ていますし,コメント中に本物のLaTeXやマークアップ言語を埋め込むことも出来ちゃうので,意外と覚えやすいはずです.

ここではよく使ういくつかのルールのみを紹介します. ドキュメントを詳しく丁寧に書きたければDoxygenの公式サイトから更に詳しいルールを調べることもできますが,ここで紹介しているルールだけでも素晴らしいドキュメントを生成できます. DoxygenはC/C++, Objective-C, C#, Fortran, PHP, Python, Java, IDL, VHDL, Tcl, D言語に対応しています. ここではC/C++言語を例に話を進めましょう.

覚えること基本

まずはコメントの書き方を. というのもC言語では,


/* コメント */

と書きますが,これではDoxygenはそのコメントを抽出してくれません. 次のように始めの*をひとつ多く書くか,始めの*に続けて!を書くとDoxygenはそのコメントを抽出するようになります.


/** このコメントは抽出されます */
/*! このコメントも抽出されます */

この形式ならば複数行に渡るコメントでもちゃんと抽出してくれます. ただし,複数行に渡るコメント中にLaTeXやマークアップ言語を混ぜて書きたい場合は次のように行頭に*置かなければなりません.


/**
 *  このように行頭にアスタリクスを置けば,
 *  \latexで書いたコメントをちゃんと処理してくれます.
 *  **Markdown記法**も処理してくれます.
*/

C++の場合,行末までのコメントを//で書きますが,この場合も上の例に倣って/をひとつ多く書くか,/に続けて!を書くことでDoxygenに抽出されるようになります.


/// このコメントは抽出されます
//! このコメントも抽出されます

函数のドキュメンテーション

何を入力すると何が返ってくるのか. どのようなことに注意すべきでどのようなバグが潜んでいるのか,といった情報はドキュメンテーションに載せるべきです. Doxygenでは次のように,函数の直前にコメントを書くとそのコメントを直後の函数の説明文として使ってくれます.


/** 2つの引数の総和を返す函数 */
int sum(int a, int b)
{
  return a+b;
}

函数の引数について説明を追加したい場合は\paramキーワードを使います.


\param 引数 説明文

函数の戻り値についての説明は\returnキーワードに続けて書きます.


\return 説明文

全部をまとめて書くと次のようになるはずです.


/**
  2つの引数の総和を返す函数
  \param a 1つ目の引数
  \param b 2つ目の引数
  \return 2つの引数の総和
 */
int sum(int a, int b)
{
  return a+b;
}

このような函数に対する説明文は定義だけでなく,ヘッダファイル内の宣言にも書くことが出来ます.

もしも,函数定義(もしくは宣言)とその説明となるコメントを離れた場所に書く場合は,次のように\fnキーワードを使ってどの函数に対するコメントなのかを示してあげる必要があります. この時,\briefキーワードに続けて説明文を書きます.


/**
  \fn int sum(int a, int b)
  \brief 2つの引数の総和を返す函数
  \param a 1つ目の引数
  \param b 2つ目の引数
  \return 2つの引数の総和
 */
int sum(int a, int b)
{
  return a+b;
}

以上のソースコードをDoxygenに読ませると次のようなドキュメントへまとめてくれます.

少し工夫したコメントを書くだけで,Doxygenはこのようにドキュメントを生成してくれます.

変数のドキュメンテーション

プログラムに大きな影響を与えるグローバル変数には説明を書くべきでしょう. Doxygenでは次のように,その変数の直前にコメントを書くことで説明としてくれます.


/** 答えを格納する変数 */
double solution;

もしくは変数宣言に続けて,始めに<を追記したコメントを書くことで説明できます.


int apple; /**< リンゴの個数 */

また,函数の時と同様に離れた位置にコメントを書きたい場合は\varキーワードを使って変数を指定し,\briefキーワードで説明を書きましょう.


/**
  \var float ratio
  \brief リンゴと砂糖の比率
 */
float ratio;

これでDoxygenは次のようなドキュメントを生成してくれます.

ちなみに,/**< コメント */の書き方は構造体のメンバへ説明を書く場合にも使えます.


/** 音楽情報を格納する構造体 */
struct music
{
  int id;       /**< ID情報 */
  int duration; /**< 曲の長さを秒で */
  char* name;   /**< 曲の名前 */
  char* artist; /**< アーティスト情報 */
  char* album;  /**< アルバム情報 */

  /** レーティング情報 */
  enum rating
  {
    GOOD, /**< いいね */
    BAD   /**< だめだね */
  } rating;
};

上のコードによって次のようなドキュメントが生成されます.

上の例の/** レーティング情報 */というドキュメンテーションを見ると分かりますが,/**< コメント */でなくても今まで通りの書き方で構造体のメンバへ説明を加えることも出来ます. 見やすい方で書きましょう. ただし,structに対する説明は\structキーワードと\briefキーワードを使うことで離れた場所にも書けますが,メンバに対する説明は上の記法でないと書けないようです. 列挙型や共用体についても同じ記法でドキュメンテーション可能です.

ファイルのドキュメンテーション

1番最初に目につく大切なドキュメントはファイルの説明です. このファイルはどんなコードを格納しているのか,簡単な説明が付いているだけでもプロジェクトの可読性は高まります. \fileキーワードと\briefキーワードの組み合わせでファイルに対する説明を追記出来ます.

test.c


/**
  \file test.c
  \brief メインファイル
 */

コードが続く...

test.h


/**
\file test.h
\brief ヘッダファイル
*/

コードが続く...

他にも\warningや\bugに続けて使用上の注意点やバグについて追記することも出来ますし,\authorに続けて著者名も追記可能です. ここでは最もシンプルな例を紹介しています.

更にバージョン番号を追記できる\versionや日付を追記出来る\dateもあります. \dateは複数回使うことで簡単な変更履歴を残すことも出来ますが,そういった内容はバージョン管理ソフトを利用した方が良いので,ドキュメントに載せるべきか否か一考の上で書き記しましょう.

実践編

8344875032513097747 https://www.storange.jp/2015/06/doxygen.html https://www.storange.jp/2015/06/doxygen.html Doxygen ドキュメント生成ツール "概要編" 2015-06-27T12:08:00+09:00 https://www.storange.jp/2015/06/doxygen.html Hideyuki Tabata Hideyuki Tabata

200 200

72 72