Doxygen入門の入門

概要

Doxygenについてまとめます

入門の入門ということで概要からインストール、簡単に試してみるところまで

どういうものかイメージができるまで使おうと思います

ちなみに今回の記事で作成したサンプルのソースコードはこちらから確認できます

※ 2018/9/29 ↓続編としてこちらの記事を作成しました、実際にGitHub PagesにDoxygenドキュメントを乗せたのでサンプルを見れるようにしました

サンプルを見ながらDoxygenの理解を深める

Doxygenについて

Doxygenとはドキュメンテーションジェネレータです
Doxygenの書き方でソースコードにコメントを書いていくと
コメントからドキュメントをHTMLとして自動生成してくれます

イメージとしては作成されたドキュメントはこのように確認できる

Doxygenの良いところはC++、C言語、Java、PHP、Pythonなど様々な言語に対応している

インストール

Linuxの場合

簡単な導入方法は以下

// インストール
$ sudo yum -y install doxygen
$ sudo yum -y install cmake graphviz graphviz-gd

上記のやり方だとdoxygenの最新バージョンが入らないので最新のバージョンを入れる

最新バージョンは以下のページから確認する
Doxygen Downloads
↑WindowsやMacへインストールする時もこちらからダウンロードできます

$ wget http://ftp.stack.nl/pub/users/dimitri/doxygen-1.8.11.linux.bin.tar.gz 
$ tar xvfz doxygen-1.8.11.linux.bin.tar.gz
$ cd doxygen-1.8.11
$ ./configure
$ sudo make
/usr/bin/install -d /usr/local/bin
/usr/bin/install -d /usr/local/doc/doxygen
/usr/bin/install -m 755 bin/doxygen    /usr/local/bin
/usr/bin/install -m 755 bin/doxytag    /usr/local/bin
/usr/bin/install: cannot stat `bin/doxytag': そのようなファイルやディレクトリはありません
make: *** [install] エラー 1

そのままだとエラーになってしまうためMakefileを修正する

// 変更点
// 2カ所コメントアウトする
$ diff Makefile Makefile.back
16c16
< #$(INSTTOOL) -m 755 bin/doxytag $(INSTALL)/bin --- > $(INSTTOOL) -m 755 bin/doxytag    $(INSTALL)/bin
19c19
< #cp -r examples $(INSTALL)/doc/doxygen --- > cp -r examples $(INSTALL)/doc/doxygen

引き続き実行していく

$ sudo make
$ sudo make install
$ /usr/local/bin/doxygen --version
1.8.11

またどの関数からどの関数を呼んでいるかをグラフで可視化することができるが、それを使うためにはGraphvizをインストールする必要がある

Graphvizダウンロードページ参考

Macの場合

以下のURLよりインストーラーをダウンロードして実行していくと導入できるはず

Doxygenダウンロードページ参考
Graphvizダウンロードページ参考

またはHomebrewを使うと簡単にインストールできる

$ brew install doxygen
$ doxygen -v
1.8.14

$ brew install graphviz
$ dot -V
dot - graphviz version 2.40.1

Windowsの場合

以下のURLよりインストーラーをダウンロードして実行していくと導入できるはず

Doxygenダウンロードページ参考
Graphvizダウンロードページ参考

設定

まずはドキュメントを生成したいディレクトリに移動した後に

$ doxygen -g

を実行するとDoxyfileが生成されるので設定を行う
例えば以下のような修正を行う

$ diff Doxyfile Doxyfile.back
--- プロジェクト名
< PROJECT_NAME = "My Sample" > PROJECT_NAME = "My Project"

--- バージョン番号
< PROJECT_NUMBER = 1.0.0 > PROJECT_NUMBER =

--- 日本語出力にする
< OUTPUT_LANGUAGE = Japanese > OUTPUT_LANGUAGE = English

--- コメントがついていなくてもドキュメント化
< EXTRACT_ALL = YES > EXTRACT_ALL = NO
---
< EXTRACT_PRIVATE = YES > EXTRACT_PRIVATE = NO
--- 
< EXTRACT_STATIC = YES > EXTRACT_STATIC = NO

--- サブディレクトリまで検索してドキュメント生成
< RECURSIVE = YES > RECURSIVE = NO
---
< GENERATE_LATEX = NO > GENERATE_LATEX = YES

--- dotツールでグラフィック表示
< HAVE_DOT = YES > HAVE_DOT = NO
---
< UML_LOOK = YES > UML_LOOK = NO
---
< CALL_GRAPH = YES > CALL_GRAPH = NO
---
< CALLER_GRAPH = YES > CALLER_GRAPH = NO
--- ↓Graphvizの実行ファイルがあるパスを記載する「$ which dot」などで調べられる
< DOT_PATH = > DOT_PATH = /usr/local/bin/

--- クラスやファイルなどの情報がツリー表示される
< GENERATE_TREEVIEW = NO > GENERATE_TREEVIEW      = YES

※ 出力結果は見やすくするため一部書き換えています

Doxygenの書き方

Doxygenコメントの書き方は普通のコメントの書き方とは違い以下の書き方で記述する必要がある

① /** ～ */
② /*! ～ */
③ /// ～
④ //! ～

例

/**
 ** @file hoge.c
 */

コマンドの一覧はこちら：特殊コマンド

使ってみる

$ mkdir src
$ vim src/Arithmetic.php
$ cat src/Arithmetic.php
<?php /** ** @mainpage ** Doxygen説明用ソースコード */ /** ** @file Arithmetic.php ** @brief 四則演算関連の処理を集めたファイル */ /** ** @四則演算を行うクラス */ class Arithmetic { /** 計算を何回行ったか */ public $count = 0; /** ** @brief 足し算を行う関数 ** @param x 項1 ** @param y 項2 ** @return xとyを足した結果 */ public function add($x, $y) { $this->count++;
        return($x + $y);
    }
}

/**
 ** @brief Arithmeticを継承したクラス
 ** 説明用なので作成しただけ
 */
class ArithmeticPlus extends Arithmetic
{
}

ドキュメントを作成する

$ doxygen

htmlディレクトリが作成されたはずなので
html/index.htmlをブラウザで表示させてみる

実際にできたページがこちら

「クラス」ページから継承関係も確認できる

クラスについてや引数などについても確認できる

続きは↓に記載しました、実際にGitHub PagesにDoxygenドキュメントを乗せたのでサンプルを見れるようにしました

サンプルを見ながらDoxygenの理解を深める

参考

• CentOS6.3にDoxygenをインストールして使ってみる
• Ｃプログラマのためのdoxygen
• 個人的なDoxygenコメントの書き方