Doxygen入門の入門

■ 目次

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

■ 概要

Doxygenについてまとめます

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

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

■ Doxygenについて

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

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

doxygen01

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

■ インストール

簡単な方法では以下

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

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

最新バージョンは以下のページから確認する
Doxygen Downloads

$ 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

■ 設定

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

$ 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
※ 出力結果は見やすくするため一部書き換えています

■ 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を継承したクラス<br>
 ** 説明用なので作成しただけ
 */
class ArithmeticPlus extends Arithmetic
{
}

ドキュメントを作成する

$ doxygen

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

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

doxygen02

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

doxygen03

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

doxygen04

■ 参考


Be First to Comment

コメントを残す

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