Doxygen入門の入門


■ 目次

  1. 概要
  2. Doxygenとは
  3. インストール
  4. 設定
  5. 使ってみる
  6. 参考

■ 概要

Doxygenについてまとめます

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

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

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

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

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

■ Doxygenについて

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

イメージとしては作成されたドキュメントはこのように確認できる
doxygen01
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
 */

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

コマンド
@mainpage doxygenで作成されるドキュメントの最初のページの説明文
@page ドキュメントのページ
@section ページ内でのセクション
@code コードの引用開始
@endcode コードの引用終了
@brief 要約説明
@detail 詳細説明
@return 戻り値について(一つの関数の説明に1つしか使用できない)
@retval 戻り値の値を複数列挙して説明
@param 引数の説明
@attention 注意文
@warning 警告文
@note 覚え書き
@bug バグを記述
@todo Todo
@deprecated 非推奨である
@pre 事前条件を記述
@post 事後条件を記述

■ 使ってみる

$ 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をブラウザで表示させてみる

実際にできたページがこちら
doxygen02
「クラス」ページから継承関係も確認できる
doxygen03
クラスについてや引数などについても確認できる
doxygen04

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

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

■ 参考


Be First to Comment

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です