4月 24, 2018

doxygen

from https://qiita.com/wakaba130/items/faa6671bd5c954cb2d02

doxygenとは

ソースコードのドキュメントツールです．
決まった形式でコメントを打ち込むと，綺麗なドキュメントを作成してくれます．
ドキュメントの出力形式は，HTMLとLaTexです．
また，オプションでgraphvizを設定してドキュメント作成すると，関数やクラス間の関係性を図にしてくれます．
OpenCVの公式ドキュメントなどは，このDoxygenで作成されています．

インストール

doxygenのインストール

doxygenのサイトの中央あたりに，doxygen-1.8.12-setup.exeがあるので，ダウンロードします．
ダウンロードしたら，doxygen-1.8.12-setup.exeを起動し，setup画面の指示に従って「next->」をクリックします[1]．

Graphvizのインストール

※これは，オプションなので，インストールしなくてもdoxygen自体は使用できます．

Graphvizは，dot言語で記述されたグラフの構造を画像ファイルへ出力してくれるアプリです．
このアプリをリンクさせることで，関数の関係性グラフ（どの関数からどの関数を呼んでいるか）が可視化され，doxygenで作成したドキュメントに埋め込まれます．

インストール方法は，Graphvizのインストールページから「同意する」を押して，windowsの安定板パッケージをダウンロードします．
ダウンロードしたgraphviz-2.38.msiを起動して，setup画面の指示に従って「next->」をクリックしていくとインストールできます[2]．

この時，Graphvizのインストール先を覚えておいてください．

使い方(コメントの書き方編)

ソースコードへ書き込むコメントの説明です．
いくら自動でドキュメント作成といってもdoxygen用のコメントの書き方をしてあげないと，
綺麗なドキュメントにはなりません．

コメントの定義

C++のコメントの書き方は，//と/**/があると思いますが，doxygenで認識されるコメントの定義は以下の書き方です[3]．
この書き方であれば，同じファイルで何種類かを使い分けても認識されます．
ドキュメントに組み込まれたくないコメントは，他の書き方で書くとドキュメントには含まれません．

/**
* 複数行のコメント用
*/

/*!
* 複数行のコメント用
*/

///
/// 複数行のコメント用
///

//!
//! 複数行のコメント用
//!

//! 1行コメント（主に変数に使用）

また，コメントの中身にもdoxygen流の書き方がありますので，
ここからはコメントの書き方を場合分けで書いていきます．
※※　ここで紹介する書き方はほんの一部です　※※

ファイル名へのコメント

作成したヘッダファイルやCPPファイルにコメントを付けるときの書き方例です．
4行すべて書く必要はなく，最低限，とがあればドキュメントに反映されます．

/**
* @file ファイル名.h
* @brief 簡単な説明
* @author 作成者
* @date 作成日
* @details 詳細な説明
*/

関数へのコメント

関数のコメントは，の後に関数の定義を書いてください．
書き方をググると結構書いていないサイトとかもあるのですが，
私の場合は，関数定義がないとドキュメントに反映されませんでした．

/**
* @fn void function(int a, int b)
* @brief 簡単な説明（～する関数）
* @param[in] a(引数名) 引数の説明
* @param[out] b(引数名) 引数の説明
* @return bool 戻り値の説明
* @details 詳細な説明
*/
bool function(int a, int &b) {
    b = a + 3;
    return true;
}

2016/11/3追記：
については，必ず必要な表記ではないため，以下のように省略することも可能です．
こちらの方が，関数を修正した時にを修正するのを忘れてドキュメントに反映されないなどの
問題がないため，便利です．
doxygenの日本語サイトにもは冗長だと書かれていました．

/**
* @brief 簡単な説明（～する関数）
* @param[in] a(引数名) 引数の説明
* @param[out] b(引数名) 引数の説明
* @return bool 戻り値の説明
* @details 詳細な説明
*/
bool function(int a, int &b) {
    b = a + 3;
    return true;
}

クラスへのコメント

クラスの場合は，から書き始めます（クラスを表す@があるのかもしれませんが，調査不足です）．
ただし，コメントの位置はクラス定義の真上に書いてください．
コンストラクタとデストラクタは，関数のようにから書き始めると正しく表示されなくなります．
これらも定義の真上に書いてください．

/**
* @brief 簡単なクラスの説明
* @details 詳細なクラスの説明
*/
class Cclass{

public:
    /**
    * @brief コンストラクタの簡単な説明
    */
    Cclass(){}
    /**
    * @brief デストラクタの簡単な説明
    */
    ~Cclass(){}

    /**
    * @fn void sum()
    * @brief 簡単な関数
    * @details 詳細な説明（クラス内の関数も普通の関数と同じように書く）
    */
    void sum();
};

マクロへのコメント

マクロへのコメントには．を使用します．
これはファイルに対するコメントが書かれていないとドキュメントに反映されないので注意してください．

/**
* @def _TEST
* @brief 簡単な説明
* @details 詳細な説明
*/
#define _TEST 0

名前空間へのコメント

/**
* @namespace Namae
* @brief 簡単な説明
* @details 詳細な説明
*/
namespace Namae{
}

変数へのコメント

変数の説明の場合は，たくさん書くことが少ないので1行コメントで書きます(必ず真上にコメント)．
もちろんこれは私の好きな書き方なので，２つめの書き方でもかまいません．
注意点は，この書き方で関数内の変数の説明を書いてしまうと，関数内部の説明文と解釈され，
関数の説明文（以下の文章）に結合されてしまいます．

//! ほにゃららで使う変数
int a;

/**
* ほにゃららで使う関数
*/
int a;

使い方(doxygen実行編)

コメントが打ち終わったら，Doxygenを起動してドキュメントを作成します．
なお，Doxygenでは様々なオプションが設定できますが，ここでは最低限の設定を行います（知識不足）．

doxygenフォルダの中の「Doxywizard」を起動します．

起動すると以下のウィンドウが起動します．
赤枠と青枠の部分を設定していきます．
Step1の赤枠はdoxygenのプロジェクトを作成するディレクトリの選択です．このディレクトリ内にソースコードが入っている場合は，
青枠の設定はスキップできます．
Project nameの赤枠には，doxygenプロジェクトのプロジェクト名を入力します．VisualStudioなどで作成したコードのプロジェクト名と一緒にしておくと管理しやすいと思います．

青枠の部分はソースコードのあるディレクトリの設定です．その下の赤枠内のScan recursivelyにチェックを入れると指定したディレクトリ以下のディレクトリを再起的に読み込みソースコードを探します．

矢印の「Mode」を選択し，チェックを「All Entities」と「Optimize for C++/CLI output」に設定します．

「Expert」タブを開き，ドキュメントの出力文字をJapaneseに設定します．

「Input」を開く，ここは，ソースコードの文字コードを設定します．
Visual Studioの場合は，Shift-JISが一般的だと思われるので，INPUT_ENCODINGを「CP932（Shift-JIS）」に設定します．

「Run」タブを開いて，「Run doxygen」ボタンを押すとドキュメント作成が実行されます．
「Show HTML output」ボタンを押すと，ブラウザが起動して作成したドキュメントが表示されます．

あとは，表示のおかしなところや，説明不足なところのコメントを修正・追加して完成です．

おまけ：関数の関係図をドキュメントに埋め込む設定

※これは先に，Graphvizをインストールしておく必要があります．

「Wizard」タブで「Diagrams」を選択し，「Use dot tool from the GraphViz package」にチェックし，必要なグラフにチェックを入れます．

「Expert」タブを開き，矢印の「Dot」を選択します．「DOT_PATH」にGraphvizのインストール先を指定する（インストールの時にインストール先を覚えておくと良いと書いたのはこのため）．正確には，Graphvizの実行ファイルが入っているbinフォルダを指定します．

あとは，「Run」タブを開いて，「Run doxygen」ボタンを押すと関係図が自動的に作成され，添付されたドキュメントが作成できます．

搜尋此網誌

姓蔡的Blogger