Doxygenについて

初めに

以前案件でDoxygen設定事項についてwikiを作成した。

そのほかにもできることが多いようなので、この機会にほかの機能についても調べ今後の案件についても活かせるシーンを見つけられたらと思う。

内容として以前のwikiの内容に重複する箇所もあるかもしれないが、ご容赦いただきたい。

---

Doxygenでできること

ライセンスについて

GPLライセンスとの記述。※リンクが2.0であったため、GPL 2.0と認識

ここではライセンスについての説明は省くがwikiを参照しておく。

doxygenの利点について

以下、三つの利点が挙げられている。

1. 文書化されたソースファイルのセットから、 オンライン・ドキュメント・ブラウザ (HTML形式) やオフラインのリファレンス・マニュアル (LaTeX 形式) を生成することができます。 RTF (MS-Word)、PostScript、ハイパーリンク PDF、圧縮 HTML、Unix man ページ形式の出力もサポートされています。ドキュメントは、ソースから直接抽出されます。これにより、ドキュメントとソースコードの一貫性を保つことがとても容易になります。
   
2. Doxygen は、文書化されていないソースファイルから、 コードの構造を抽出するように設定することができます。 これにより、大規模で分散化されたソースの中を探ることが容易になります。 様々な要素間の関係が、内包・依存図、継承図、 およびコラボレーション図により視覚化されます。しかもすべて自動的に生成されます。
3. また、Doxygen を「乱用 (abuse)」して、 通常のドキュメントを作成することもできます (このマニュアルでやっているように)。
   ーー日本語版サイトより抜粋

対応環境について

• Linux
• windows

• Mac OS X

• ほとんどのunix

対応言語について

日本語版サイトを参照すると以下の言語に対応しているとのこと。

今回私はC#で使用した。

• C++
• C
• Java
• Objective-C
• Python
• IDL (Corba、Microsoft 風)
• Fortran
• VHDL
• PHP
• C#
• (ある程度)D

出力フォーマットについて

日本語版サイトを参照すると以下の形式の出力形式がサポートされているとのこと。

今回私はHTMLにて生成した。

• HTML
  
• LaTeX
  
• Man pages
  
• RTF
  
• XML
  
• Qt Help Project (.qhp)
  

間接的に生成可能

• Compiled HTML Help (別名 Windows 98 help)
  
• Qt Compressed Help (.qch)
  
• PostScript
  
• PDF
  

生成後の例についてリストアップされていたため、参考までに以下にリンクを記載しておく。

Example of output generated by doxygen
Projects using doxygen

---

使用するために

インストール

ここでは割愛することとする。

以下の日本語版サイトのインストール手順を参照する。

インストール

もしくは以下の記事も参考にさせていただいた。

Doxygenをインストールしてつかってみた（Windows）

また、クラス図を描画のためのGraphvizのインストールについては以下の記事を参照する。

【Windows】Doxygenをインストールして使う

---

使用方法について

以下、機能のほんの一部をかいつまんで紹介している。

特徴についてはこちらにまとめられている。

基本的な使用方法

用意したDoxyfileもしくは以下のコマンドで、Doxyfileを自動生成させる。

$ doxygen.exe -g

Doxyfileに生成するドキュメントについての設定を記述する。

Doxyfileのあるディレクトリ下で以下のコマンドを実行する。

$ doxygen

同じ階層もしくは指定した階層に、Doxyfileの設定内容に沿ったドキュメントが作成される。

詳しくは以下を参照していただきたい。
Doxygen の使い方

なお、GUIでの操作も可能である。

出力対象のリポジトリの指定方法について

DoxygenのINPUTの値で指定する。

GUIではSource code directoryに値が入る。

表示されているPTAHから指定部分を削除

以下のSTRIP_FROM_PATHとSTRIP_FROM_INC_PATHを変更することで、出力結果のFile Listのパス部分から記述部分を削除できる。

実際のPATH: C:\work\path\sample\test\

削除したいPATH: C:\work\path\

期待するPATH: sample\test

コメントを付ける

以下にいくつか例を記述する。

関数にこついてコメントをつける例

以下はC#の例。

//***************************************************************************
/// <summary> 
/// 関数の概要説明
/// </summary>
/// <param name="text">引数についての説明</param>
/// <returns>戻り値の説明</returns>
//***************************************************************************
private String Hello( String text ) {

クラスについてコメントをつける例

以下はC#の例。

/// <summary>
/// クラスの概要説明
/// </summary>
/// <remarks>
/// 備考
/// </remarks>
class Person
{

メンバ変数についてコメントをつける例

以下はC#の例。

/// <summary>
/// メンバ変数の概要説明
/// </summary>
public int Num { get; set; }

ファイル名へのコメントを付ける例

ヘッダファイルやCPPファイルにコメントをつける際の例。

@fileと@briefがあればドキュメントに反映される。

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

参考にさせていただきました。

• doxygenを使用してC#のドキュメントを自動生成する(その1)
• doxygen コメントその②C♯編
• Doxygen - TakeAsh.net
• 最近覚えた便利アプリ[doxygen]

リスト

doxygenではリストを作成することも可能。
以下はダッシュを使う方法を紹介する。

行の始まりにカラム位置の揃ったマイナス記号をつけると黒丸付きリストを生成。

マイナス記号の後にハッシュ (#) を置くことで数字付きリストとなる。

字下げによる入れ子も可能である。

/**
 * リストの前のテキスト
 * - list item 1
 *   - sub item 1
 *     - sub sub item 1
 *     - sub sub item 2
 *     . 
 *     上の.は sub sub item list を終了します。
 *     最初の sub item に対するテキスト
 *   .
 *   上の.は最初の sub item を終了します。
 *   最初の list item に対するテキスト
 *   - sub item 2
 *   - sub item 3
 * - list item 2
 * .
 * 同じパラグラフのテキスト
 *
 * 新しいパラグラフのテキスト
 */

結果は以下のようになる。

より詳しくは以下を参照

リスト

出力フォーマットの指定

Doxyfileの値を指定することで出力フォーマットを変更することが可能である。

• HTML
  GENERATE_HTMLがYESに設定されている場合 に生成

• LaTeX
  
  GENERATE_LATEXがYES に設定されている場合に生成

• Man pages
  
  GENERATE_MANがYESに設定されている場合に生成

• RTF
  
  GENERATE_RTFがYESに設定されている場合に生成

• XML
  
  GENERATE_XMLがYESに設定されている場合に生成

• Qt Help Project (.qhp)
  
  GENERATE_QHPがYESに設定されている場合に生成

以下は間接的に生成可能

• Compiled HTML Help (別名 Windows 98 help)
  
  GENERATE_HTMLHELP が YES に設定されている場合
  
  HTML → HTML Help workshop を用いる

• Qt Compressed Help (.qch)
  
  GENERATE_QHP がYES

qhelpgeneratorを用いてHTML出力から生成

• PostScript
  
  出力ディレクトリ内で、make ps を実行 → LaTeX出力から生成
  最もよい結果を得るには、PDF_HYPERLINKSをNOに設定してください。

• PDF
  
  出力ディレクトリ内で、make pdfを実行 → LaTeX 出力から生成
  
  PDF出力を改善するには、設定ファイルでUSE_PDFLATEXをYESに設定することで、pdflatexの使用を有効に
  
  PDF ファイルにハイパーリンクを設定するには、設定ファイルで PDF_HYPERLINKSをYESに設定

式のインクルード

Doxygenでは、LaTeXの式を出力することが可能である。HTML(画像として)とLaTeX出力でのみ動作する。

HTMLでは以下のツールをインストールしておく必要があります。

• latex:LaTeXコンパイラ
• dvips:DVIファイルを PostScriptファイルに変換するツール。
• gs:PostScriptファイルをビットマップに変換するGhostScriptインタプリタ。

式のインクルードには3つの方法がある。

1. 処理中のテキストに現れる in-text 式を使う。 これらの式は、\f$ コマンドのペアで囲む。

\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$。

結果は以下のようになる。

1. 別の行に中央揃えで表示される、番号無しの式。 これらの式は、\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]

結果は以下のようになる。

1. 術環境内にない式などのlatex要素は\f{environment}を使って指定する。
   ここでの環境とはLaTeX環境の名前で、\f}コマンドで終了させます。等式の配列を例とする。

   \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}

結果は以下のようになる。

詳細については以下を参照する。

式のインクルード

特殊コマンド

以下のページを参考にしている。

特殊コマンド

\if <セクションラベル>

条件付きドキュメント・セクションを記述します。

対応する\endifコマンドで終了。

デフォルトでは、条件付きセクションは無効です。

有効にするには設定ファイルで

ENABLED_SECTIONSタグの後に セクションラベルを置く必要がある。

  /*! 無条件に表示されるドキュメント
   *  \if Cond1
   *    Cond1が設定されていれば含まれる
   *  \endif
   *  \if Cond2
   *    Cond2が設定されていれば含まれる
   *    \if Cond3
   *      Cond2,Cond3が設定されていれば含まれる
   *    \endif
   *    他のテキスト
   *  \endif
   *  無条件のテキスト
   */

\todo { TODO を記述するパラグラフ }

TODO項目を記述するパラグラフを開始します。 この記述により、別の TODO リストにも項目が追加されます。

以下のように文字列の強調や装飾も可能。

\a <単語>

特別なフォントを使用して、引数 <単語> を表示する。

  ... the \a x and \a y coordinates are used to ...

結果は以下のようになる。

\code

コードブロックを開始する。

コードブロックは通常のテキストとは区別して扱われ、 C/C++ のコードとして解釈される。

ドキュメント化されるクラスとメンバーの名前は、 ドキュメントへのリンクで自動的に置換される。

\endcodeで終わる。

---

参考にさせていただいたもの

ありがとうございます。

• 日本語版サイト
• wiki

• 最近覚えた便利アプリ[doxygen]

• Doxygenをインストールしてつかってみた（Windows）

• 【Windows】Doxygenをインストールして使う

• doxygenを使用してC#のドキュメントを自動生成する(その1)

• doxygen コメントその②C♯編

• Doxygen - TakeAsh.net