Doxygenについて

# Doxygenについて

## 初めに

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

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

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

---

## Doxygenでできること

### ライセンスについて

[GPLライセンス](http://www.gnu.org/licenses/old-licenses/gpl-2.0.html)との記述。※リンクが2.0であったため、GPL 2.0と認識

ここではライセンスについての説明は省くが[wiki](https://ja.wikipedia.org/wiki/GNU_General_Public_License)を参照しておく。

### doxygenの利点について

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

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


### 対応環境について

- Linux
- windows
- Mac OS X

- ほとんどのunix

### 対応言語について

[日本語版サイト](http://www.doxygen.jp/)を参照すると以下の言語に対応しているとのこと。

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

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

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

[日本語版サイト](http://www.doxygen.jp/output.html)を参照すると以下の形式の出力形式がサポートされているとのこと。

今回私は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](https://www.doxygen.nl/results.html)
[Projects using doxygen](https://www.doxygen.nl/projects.html)

---

## 使用するために

### インストール


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


以下の日本語版サイトのインストール手順を参照する。   
[インストール](http://www.doxygen.jp/install.html#install_bin_windows)


もしくは以下の記事も参考にさせていただいた。   
[Doxygenをインストールしてつかってみた（Windows）](https://couraeg.hatenablog.com/entry/2020/05/09/214754#%E3%82%BB%E3%83%83%E3%83%88%E3%82%A2%E3%83%83%E3%83%97)

また、クラス図を描画のための`Graphviz`のインストールについては以下の記事を参照する。   
[【Windows】Doxygenをインストールして使う](https://www.yokoweb.net/2020/03/01/windows-doxygen-install/#toc1)

---

## 使用方法について

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

特徴については[こちら](http://www.doxygen.jp/features.html)にまとめられている。

### 基本的な使用方法

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

```bash
$ doxygen.exe -g
```

`Doxyfile`に生成するドキュメントについての[設定](http://www.doxygen.jp/config.html#cfg_tab_size)を記述する。

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

```bash
$ doxygen
```

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/269902/c70134cc-afd1-11ce-5a57-2677967d843a.png)


詳しくは以下を参照していただきたい。
[Doxygen の使い方](http://www.doxygen.jp/doxygen_usage.html)

なお、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`


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/269902/42a8d279-c1e7-b4ed-96c0-155c967b257e.png)


### コメントを付ける

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

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

以下はC#の例。

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

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

以下はC#の例。

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

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

以下はC#の例。

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

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

ヘッダファイルやCPPファイルにコメントをつける際の例。   
@fileと@briefがあればドキュメントに反映される。

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


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

- [doxygenを使用してC#のドキュメントを自動生成する(その1)](http://nanoappli.com/blog/archives/294)
- [doxygen コメントその②C♯編](http://693sharpsharp.blog.fc2.com/blog-entry-3.html)
- [Doxygen - TakeAsh.net](https://wiki.takeash.net/Doxygen.md#%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E6%9B%B8%E3%81%8D%E6%96%B9-c)
- [最近覚えた便利アプリ[doxygen]](https://qiita.com/wakaba130/items/faa6671bd5c954cb2d02)

### リスト

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

行の始まりにカラム位置の揃ったマイナス記号をつけると黒丸付きリストを生成。   
マイナス記号の後にハッシュ (#) を置くことで数字付きリストとなる。    

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

```cpp
/**
 * リストの前のテキスト
 * - 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
 * .
 * 同じパラグラフのテキスト
 *
 * 新しいパラグラフのテキスト
 */
```

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/269902/e0fc4efc-fe48-7cbd-f8f1-34da490881d6.png)


より詳しくは以下を参照   
[リスト](http://www.doxygen.jp/lists.html)

### 出力フォーマットの指定

`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$ コマンドのペアで囲む。

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/269902/4a16eebb-5c52-ff59-34c7-09b62abd591b.png)

2. 別の行に中央揃えで表示される、番号無しの式。 これらの式は、`\f[` と `\f]`コマンドで囲う。

```cpp
  \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]
```
結果は以下のようになる。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/269902/2bc5a56f-db36-4937-4472-f04a2881ab4a.png)


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

```cpp
   \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}
```
結果は以下のようになる。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/269902/f4942ccb-408a-df80-64d7-b7e015af0d1f.png)


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

[式のインクルード](http://www.doxygen.jp/formulas.html)

### 特殊コマンド

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

[特殊コマンド](http://www.doxygen.jp/commands.html)

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

条件付きドキュメント・セクションを記述します。   
対応する`\endif`コマンドで終了。   
デフォルトでは、条件付きセクションは無効です。   

有効にするには設定ファイルで   
`ENABLED_SECTIONS`タグの後に セクションラベルを置く必要がある。

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

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

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


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

#### \a <単語>

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

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

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

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/269902/4c113297-1d5f-6925-da9c-76f48f646ae6.png)


#### \code

コードブロックを開始する。   
コードブロックは通常のテキストとは区別して扱われ、 C/C++ のコードとして解釈される。    
ドキュメント化されるクラスとメンバーの名前は、 ドキュメントへのリンクで自動的に置換される。   
`\endcode`で終わる。

---

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

ありがとうございます。

- [日本語版サイト](http://www.doxygen.jp/)
- [wiki](https://ja.wikipedia.org/wiki/GNU_General_Public_License)
- [最近覚えた便利アプリ[doxygen]](https://qiita.com/wakaba130/items/faa6671bd5c954cb2d02)


- [Doxygenをインストールしてつかってみた（Windows）](https://couraeg.hatenablog.com/entry/2020/05/09/214754#%E3%82%BB%E3%83%83%E3%83%88%E3%82%A2%E3%83%83%E3%83%97)
- [【Windows】Doxygenをインストールして使う](https://www.yokoweb.net/2020/03/01/windows-doxygen-install/#toc1)

- [doxygenを使用してC#のドキュメントを自動生成する(その1)](http://nanoappli.com/blog/archives/294)
- [doxygen コメントその②C♯編](http://693sharpsharp.blog.fc2.com/blog-entry-3.html)
- [Doxygen - TakeAsh.net](https://wiki.takeash.net/Doxygen.md#%E3%82%B3%E3%83%A1%E3%83%B3%E3%83%88%E3%81%AE%E6%9B%B8%E3%81%8D%E6%96%B9-c)