Doxygen を使う

2018年10月4日

はじめに

プログラムのソースコードのドキュメントを生成するツールである Doxygen の使い方について。

環境

  • Doxygen 1.8.11
  • Ubuntu 16.04 LTS

セットアップ

インストール。

$ sudo apt-get install doxygen graphviz

graphviz はグラフを描くのに必要。

設定

設定ファイルを生成する。

$ doxygen -g Doxyfile

設定ファイルを編集する。以下のような設定を行う。

PROJECT_NAME           = "My Project"

プロジェクト名を設定する。

PROJECT_NUMBER         = 0.1

バージョン番号を設定する。

OUTPUT_LANGUAGE        = Japanese

日本語に設定する。

EXTRACT_ALL            = YES

コメントのついてないものもすべてドキュメントに含める。

EXTRACT_PRIVATE        = YES

private メンバーも見えるようにする。

EXTRACT_STATIC         = YES

static メンバーも見えるようにする。

SOURCE_BROWSER         = YES

ソースコードをドキュメントに含める。

INLINE_SOURCES         = YES

関数、クラス、列挙型の本体をそれぞれの説明に直接入れる (これが NO でも SOURCE_BROWSER = YES であればコードの確認はできる)。

GENERATE_TREEVIEW      = YES

ツリー状のインデックス構造を生成する。

GENERATE_LATEX         = NO

LaTeX が不要の場合は NO にする。

実行

設定ファイルを指定して実行する。

$ doxygen Doxyfile

html/index.html をブラウザで開く。

ドキュメント用のコメント

C/C++ において、以下のような特殊なコメントを書くと、内容がドキュメントに反映される。

/*!
 * ...
 */

/**
 * ...
 */

//!
//! ...
//!

///
/// ...
///

ファイルの説明

ファイルの先頭に次のように書く。

/*!
 * \file myprog.c
 * \brief 私のプログラム
 * \author 私
 */

あるいは

/**
 * @file myprog.c
 * @brief 私のプログラム
 * @author 私
 */

"\file"、"@file" はタグで、特別な説明のために用いる。

  • \file : ファイル名
  • \brief : 概要
  • \author : 作者

関数、構造体、クラスの説明

関数、構造体、クラスの前にドキュメント用コメントを書くと、それぞれの説明としてドキュメントに反映される。

/*!
 * \brief 使い方の表示
 */
static void printUsage(void);

"\brief" で概要を書く。そのまま書くと詳しい説明になる。

/*!
 * \brief 点データ
 */
typedef struct Point {
    double x; //!< x座標
    double y; //!< y座標
} Point;

"//!< ..." はメンバーの説明になる。

タグ

  • \param[in,out,inout] : 引数の説明
  • \return : 返り値の説明
  • \retval : 返り値の値ごとの説明

リスト

リストを書くには次のようにする。

/*!
 * - アイテム1
 *   - アイテム1.1
 *   - アイテム2.1
 * - アイテム2
 ...

"-" の代わりに "-#" を用いると数字付きリストになる。

HTML も使える。

式

LaTeX が使える環境であれば、"\f$" と "\f$" のあいだに LaTeX 形式の式を書くことができる。