Doxygenについて
初めに
以前案件でDoxygen設定事項についてwikiを作成した。
そのほかにもできることが多いようなので、この機会にほかの機能についても調べ今後の案件についても活かせるシーンを見つけられたらと思う。
内容として以前のwikiの内容に重複する箇所もあるかもしれないが、ご容赦いただきたい。
Doxygenでできること
ライセンスについて
GPLライセンスとの記述。※リンクが2.0であったため、GPL 2.0と認識
ここではライセンスについての説明は省くがwikiを参照しておく。
doxygenの利点について
以下、三つの利点が挙げられている。
- 文書化されたソースファイルのセットから、 オンライン・ドキュメント・ブラウザ (HTML形式) やオフラインのリファレンス・マニュアル (LaTeX 形式) を生成することができます。 RTF (MS-Word)、PostScript、ハイパーリンク PDF、圧縮 HTML、Unix man ページ形式の出力もサポートされています。ドキュメントは、ソースから直接抽出されます。これにより、ドキュメントとソースコードの一貫性を保つことがとても容易になります。
- Doxygen は、文書化されていないソースファイルから、 コードの構造を抽出するように設定することができます。 これにより、大規模で分散化されたソースの中を探ることが容易になります。 様々な要素間の関係が、内包・依存図、継承図、 およびコラボレーション図により視覚化されます。しかもすべて自動的に生成されます。
- また、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
生成後の例についてリストアップされていたため、参考までに以下にリンクを記載しておく。
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ではリストを作成することも可能。
以下はダッシュを使う方法を紹介する。
行の始まりにカラム位置の揃ったマイナス記号をつけると黒丸付きリストを生成。
マイナス記号の後にハッシュ (#) を置くことで数字付きリストとなる。
字下げによる入れ子も可能である。
/**
* リストの前のテキスト
* - 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つの方法がある。
- 処理中のテキストに現れる 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$。
結果は以下のようになる。
- 別の行に中央揃えで表示される、番号無しの式。 これらの式は、
\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]
結果は以下のようになる。
- 術環境内にない式などの
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で終わる。
参考にさせていただいたもの
ありがとうございます。