感激！？ Doxygenで文書作成（研究・開発用）

前文

Doxygenというドキュメントジェネレーターが世の中にはある．
作成済みライブラリのコメントから，ドキュメントを勝手に，かついい感じに作成してくれるツールである．
多くのライブラリではこのツールを，公式が言っているとおりにドキュメント生成ツールとして使用してきた．
しかし，そうであろうか．果たして，本当にDoxygenはドキュメント生成ツールなのであろうか．
何事も疑ってみることが肝心ではなかったか．

セリヌンティウスはメロスを疑って
「えっ？　身代わり？　いやいや，だって，君，帰ってこないじゃん．」
「ていうか，君に妹なんていたっけ？」
「帰ってこなかったら，俺，死刑じゃん．俺の首が飛んじゃうよ？！」
「俺の首，まあまあ，飛ぶよ？　となり町ぐらいまでなら飛んじゃうよ？」
などという対応をすべきでなかったか．

まあ，このような塩対応をすることにより，メロスは死刑．走れメロスの物語はトゥルーエンドをむかえることになり
全国の小学生が半裸の男がジョギングする話を読まなくて済むようになり，現実では幸せな人が増加する．
従って，疑うことはいいことである．

本稿では，Doxygenで文書を作成するために有益と思われる設定を抜粋するものである．
特に，研究，開発などで資料をまとめる人向けの設定を説明するが，そうでない人にも有用な感じになるように説明させていただければと存じます．ハイ．

参照

本稿で使用したコマンドなどを反映済みのドキュメントを
サンプルページ
に置きました．

また，本稿で使用した設定などを反映済みのものを
github
に置きました．

よろしければ，使ってやってください．

また，間違いがあった場合は，マサカリ待ってます．

0. Doxygenの利点

1. Doxygenはどの環境でも使用できる．
2. 多くのオープンソースのライブラリで使用されているから，ここらで，使い方を覚えておいたほうがよろし
3. 自作ライブラリのドキュメント化にも使える
4. 基本的に自動でドキュメントを作成してくれる
5. マークダウンで書ける
6. HTMLでも書ける
7. 数式もTexもサポート
8. HTML,XML,Texなどに出力可能

あれ？　doxygenをやらない理由が見当たらない．．．

1. Doxygen　事始め

1.1 doxywizard

$ doxywizard 

とすることにより，簡単にDoxygenの設定が行えるGUIが立ち上がる．
ここでは，プロジェクト名やバージョン，ソースコードの場所や，生成されるHTMLをどのディレクトリに設置するかなどを設定可能
設定を終えると，Doxyfileが作成される．

1.2 doxygen

doxygen Doxyfile

とすることで，すでにあるDoxyfileを読み込んで，設定されているとおりに，ドキュメントを生成する．
このコマンドは，ライブラリを外部から持ってきた時に行うことが多い．
もちろん，自分で作成したDoxyfileからHTMLを作成するときにも使用します．

1.3 ファイル

1.3.1　拡張子

各種プログラミング言語のソースコードを除いて，Doxygenに文書として使用されるファイルの拡張子は

• dox
• md

の２種類である．doxはDoxygen標準の文書ファイルであり，mdはご存知，マークダウンである．

1.3.2 構成

Doxygenのファイルの種類は以下のようになっています．

• Doxyfile (設定ファイル本体）
• DoxygenLayout.xml (構成を設定するファイル,無くてもいい，デフォルトでは無い）
• xxx.dox (文書本体，いくつあってもいいよ.無くてもいい）
• xxx.md (文書本体，いくつあってもいいよ.無くてもいい)

ぶっちゃけ，文章はdoxygenが自動でソースコードを解析して作成するので，無くてもいい．

2. コマンド

doxファイルに使用可能なコマンドを紹介します．
関数やクラスのコメントの仕方は，他の方がいろいろわかりやすく書いてくださっているので，
そちらを参考にしてください．当記事では，その他の文章，特に，doxやmdに書くであろう技術文章に
使用するコマンドについて説明します．

ちなみにDoxygenはファイル中のコメントを抜き出すというスタイルなので，
doxファイルは全体をコメントアウトしてください．
要は，最初の行と，最後の行を下記のようにしてください．C言語風のコメントアウトがおすすめです．

xxx.doxの中身

/**
(本文）
(本文）
(本文）
**/

2.1 (main)page <名前> (タイトル)

doxygenのページを作成するコマンド

メインページ作成

\mainpage <名前> (タイトル)

もしくは

通常のpage作成

\page <名前> (タイトル）

doxファイル１つにつき１つの名前を付けます．
いや，複数でもいいですけど，１つにしたほうが整理しやすいと思うんですよね．
そういうわけで，各ファイルの先頭では，このdox(md)ファイルが何を表すのか上記のコマンドでタイトルなどを宣言してください．
ちなみに，１つのプロジェクトに１つのmainpageが存在し，pageはそれにぶら下がるような構造になります．

ここで，名前とタイトルっておんなやないか！と賢明な諸兄なら気づくかもしれないが，
<タイトル>は文章に表示されるもので，<名前>は，これを使って他のファイルから参照をします．
doxygen内で使えるURLみたいなもので，

\ref <名前> "テキスト"

とすると名前でもってdoxygen内での名前解決が図られ，テキストの文字でもってそのページヘのリンクが作成されます．
まあ，マークダウンでいうと

[テキスト](名前)

となります．もちろん，マークダウンの記法でも同様にリンクを作成することができます．

2.2 \section <名前> (タイトル)

章，節を作成するコマンド

\section <名前> (タイトル)
\subsection <名前> (タイトル)
\subsubsection <名前> (タイトル)

もちろん，マークダウンも使用可能で

# h1
## h2
### h3

となります．

2.3 リンク

1. ページ，セクションへのリンク

[テキスト](名前)

マークダウンと同様です
テキストが青文字表記された，その名前を持つsectionもしくはpageへのリンクが作成されます．
実際は\refコマンドと合わせて，

[Section1](\ref sec1)

という感じに使います．

2. クラス，クラスメソッド，関数へのリンク

文章中に，それらが出てきた場合，自動でリンクが作成されますが，
明示的にリンクを作成したい場合，以下のいずれかのコマンドをを使用してください．

• <関数名> "("　<引数リスト> ")"

func(const std::string&, bool)

• <関数名>"()"

func()

• ::<関数名>

::func

• (<クラス名> "::")n <関数名> "(" <引数リスト> ")"

class::func(std::stinrg&, bool)

• (<クラス名> "::")n <関数名> "(" <引数リスト> ")"<修飾子>

class::func(std::string&, bool) private

• (<クラス名> "::")n <関数名> "()"

class::func()

• (<クラス名> "::")n <関数名> > class::func

3. 変数,typedef,enum,defineへのリンク

文章中にそれらが出てきた場合，自動でリンクが作成されますが，
明示的にリンクを作成したい場合，以下のいずれかのコマンドを使用してください．

• ::var

::var

• class::var

class::var

．．．ほとんど，関数へのリンクと同じです．
ホントはもっと，指定する方法があるのですが，あまりに多すぎて力尽きました．
詳しくは，doxygenのリンクコマンドの説明ページを見てください．
実際の使用例も交えて解説してくれています．

2.4 [TOC]

Table of Contentsを作成するコマンド

2.5 \author (著者の名前)

著者の項目を作成するコマンド

2.6 \version <バージョン番号>

バージョンを記述する項目を作成するコマンド

2.7 \date <日付>

日付を記述する項目を作成するコマンド

2.8 \copyright <ライセンス>

ライセンスを記述する項目を作成するコマンド

2.9 \attention <内容>

複数行に渡るアテンションパラグラフを形成するコマンド

2.10 \warning <内容>

複数行に渡る警告パラグラフを形成するコマンド

2.11 \note <内容>

複数行に渡る注意事項を形成するコマンド

2.12 \todo <内容>

複数行に渡るやることリストを形成するコマンド
Related Pagesに自動的にTodoリストが作成されます

2.13 \pre <内容>

複数行に渡る事前条件の項目を形成するコマンド

2.14 \post <内容>

複数行に渡る事後条件の項目を形成するコマンド

2.15 \bug <内容>

複数行に渡るバグの項目を形成するコマンド
Related pagesに自動的にbugリストが作成されます．

2.16 \per <パラグラフのタイトル> 内容

段落を形成するコマンド

2.17 \remark 内容

注釈を形成するためのコマンド

2.18 フォント

\a, \b, \cの後ろに続く文字に影響がでます．

\a Italic
\b Bold
\c Type

2.19 \li <内容>

リストを作成するコマンドです
ネストはできません．ネストを使用したい場合はマークダウンの記法を使用してください．

2.20 \code{.拡張子}

ソースコードをシンタックスハイライトこみで表示する方法

\code{.cpp}
int main(void)
{
std::cout << "doxygen" std::endl;
}
\endcode

2.21 \dot

graphvizを用いて，プラント図やクラス図を綺麗に書いて埋め込むコマンド

\dot
digraph example {
node [shape=record, fontsize=10];
b [label="class B"];
c [label="class C"];
b -> c [arrowhead="open", style="dashed"];
}
\enddot

2.21　数式

Tex記法を利用して数式を作成するコマンド

1. インライン数式

\fと\fで囲むと，その間がTexの数式として解釈されます．

\f$(x_1,y_1)\f$ と \f$(x_2,y_2)\f$ の間の距離は \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$。

$(x_1,y_1)$ と $(x_2,y_2)$ の間の距離は $\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}$

2. 中央揃えの番号なし数式

複数行に渡る場合は\f[と\f]で囲むと数式処理されます．

\f[
    |I_2|=\left| \int_{0}^T \psi(t) 
             \left\{ 
                u(a,t)-
                \int_{\gamma(t)}^a 
                \frac{d\theta}{k(\theta,t)}
                \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi
             \right\} dt
          \right|
  \f]

3. Texコマンドを使用しての数式

eqnarrayなどのTexのコマンドを使用することも可能です．

   \f{eqnarray*}{
        g &=& \frac{Gm_2}{r^2} \\ 
          &=& \frac{(6.673 \times 10^{-11}\,\mbox{m}^3\,\mbox{kg}^{-1}\,
              \mbox{s}^{-2})(5.9736 \times 10^{24}\,\mbox{kg})}{(6371.01\,\mbox{km})^2} \\ 
          &=& 9.82066032\,\mbox{m/s}^2
   \f}

3. マークダウンのサポート

マークダウンとdoxygenの記法は混ぜて使用することが可能です．
基本的に殆どのマークダウン記法がサポートされています．
表などはマークダウンで書くと便利です．

通常のマークダウンとの差異は以下の２つです．

コードブロック

通常コードブロックを作成するためにはバッククオートを使用しますが，doxygenでは代わりにチルダを使用します．

リンク

URLを使用してリンクを使用するときには，通常のマークダウンの記法を使用しますが，
doxygen内のページなどへのリンクを作成するときには，通常のマークダウンのリンクのコマンドのURLの部分に
#+名前を書きます．

h1というテキストにheader1という名前を持つセクション,orページへのリンクを作る場合は以下のようになります．

[h1](#header1)


4. HTML

HTMLコマンドを使用することも，HTMLをページの中に埋め込むこともできます．

1. HTMLコマンド

利用可能なHTMLコマンドの一覧はこちら

2. HTML埋め込み

HTMLコードを\htmlonlyと\endhtmlonlyで囲むことで任意のHTMLコードを埋め込むことが可能です．

\htmlonly
<progress value="70" max="100">90 %<\progress>
\endhtmlonly

5. CSS

doxygen用のcssコードをgithubとかで公開されています．
わたしのお気に入りはアップルのSDKに影響を受けたCSSです．
ここで公開されています．

ダウンロードしてきて，
Doxyfileのある場所に

• customdoxygen.css
• DoxygenLayout.xml

の２つのファイルをコピーしましょう．
そして，Doxyfileの

• HTML_EXTRA_STYLESHEET =
• LAYOUT_FILE =

というように空白になっている項目に，先ほどコピーしたファイルを設定しましょう．

• HTML_EXTRA_STYLESHEET = ./customdoxygen.css
• LAYOUT_FILE = ./DoxygenLayout.xml

最後に，

doxygen Doxyfile

とするコマンドを走らせると
CSSが適用されたものが出来上がります．