Doxygenを使ってドキュメントをつくる

# Doxygenを使ってドキュメントをつくる

## どんなドキュメントをつくりたい？

**C#で書いたアプリケーションのドキュメントをつくりたい！**

**「このシステムは何なんだ！説明しろ！」**と言ってくる何もしらない人への導入から
開発に参画してコードの変更に携わる人への説明まで、手広くカバーしたい。

私はそんなドキュメントを作りたい。できるだけ簡単に。

## ドキュメント作成ツール「Doxygen」

Doxygenというツールがあります！
ソースコードとマークダウンをうまく折り合わせてHTML形式のページを作ってくれるツールです。
HTML以外にも出力フォーマットはたくさんあります。
![outformat.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/2ce09829-8009-919d-eadf-bd21e6991514.png)


### 何ができるの？どう使うの？

すでに**スバラシイ記事**（次節）が存在します。
この記事は、スバラシイ記事をトレースして、自分なりにちょっと補足してみたものです。

## まずは、ここを読みましょう。超参考サイトです

基本的には下記の記事（様）を読めばよいと思います。
本記事は、下記記事を嚙み砕いてごく一部を吐き戻したものです。

- [DoxygenによるMarkdown形式からのドキュメント作成](https://zenn.dev/mebiusbox/articles/bca221e0cac13f)
  - 序盤の環境づくりや、フォルダー構成はほとんどこの記事を参考にさせていただきました
- [感激！？　Doxygenで文書作成（研究・開発用）](https://qiita.com/harumo11/items/c51228fba7879144e12c)
  - 使う頻度が多そうなコマンドをピックアップされていてスバラシイです
- [公式](http://www.doxygen.jp/)
  - 上記2記事で理解が追い付かない点は、公式マニュアルを読んで補完

## Doxygenを使う準備

何はともあれ公式サイトからツールをダウンロード
[doxygenダウンロードサイト](https://www.doxygen.nl/download.html#latestsrc)

ついでにVS Codeもインストールしておきます。

### インストールしてパスを通す

CLIから使うためにパスを通します。
2021年3月末現在の最新バージョンは**1.9.1**です。

``` PowerShell
# 私の環境でdoxygenがインストールされた場所
>where doxygen
C:\Program Files\doxygen\bin\doxygen.exe

# バージョン
> doxygen --version
1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b)
```

### VS Codeの設定

VS Codeを使って話を進めます。

`.vscode/tasks.json`にビルドタスクを書いて置いておくと
`Ctrl + Shift + b`で簡単に変更を反映させることができます。

``` PowerShell
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "type": "shell",
            "command": "doxygen Doxyfile",
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "reveal": "always",
                "clear": true,
                "panel": "shared"
            },
            "options": {
                "cwd": "${workspaceRoot}/workspace/build"
            }
        }
    ]
}
```

`tasks.json`の置き場所はココ↓

![taskjson.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/b7f5bccd-3dd2-75f3-20d6-9f12a889aa3e.png)

## ドキュメントの中にリンクを貼る

基本的にはマークダウン形式で記述できるようです。
ただし、同一`src`内にある別の`.md`ファイルへのリンクの仕方だけは違う。

たとえば下記のような`page1.md`へのリンクを貼るときは、マークダウン形式の書き方では飛べません。

``` PowerShell
# ページ1 {#page1}
ここはpage1です
```

別ページへ飛ぶときは、`\ref`キーワードを使います（下表いちばん右）

同一`md`ファイル内のセクションへのリンク|外部|別`md`ファイルへのページリンク
---|----|---
`[リンク先](#section)`|`[リンク先](URL)`|`[リンク先](\ref page1)`

VS Codeのプレビューでは、refキーワードはプレーンテキストで表示される。

![vscode00.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/31d7b119-9cae-4386-9408-c83e0e65ae1d.png)

## ドキュメントの中に画像を埋め込む

JPG, PNG, GIFなどの画像をページの中に埋め込む方法を説明します。
少なくとも上記3フォーマットは使えました。(Ver.1.9.1で検証)

### 画像の場所を指定する必要があります

doxygenのGUIから画像が格納されている場所を指定します
次節で使う画像`jjj.jpg`はココで指定したパスからの相対パスになります


![image-path.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/ee45cbb6-5fc6-eab5-f0d9-b8f647b5a91f.png)

### 画像を埋め込む文法は2種類ある

doxygen特有の書き方と、マークダウン形式の書き方の2通りが使えます。

- [doxygenのイメージ埋め込み方法](http://www.doxygen.jp/commands.html#cmdimage)を使うと、画像の下にキャプションがついて、かつ画像がセンターに表示される
- マークダウン形式で画像を埋め込むと、左寄せで表示される

``` PowerShell
# doxygenのフォーマット
\image html "jjj.jpg" "これはJPG画像です"

# マークダウン形式
![alt-text](jjj.jpg)
```
`Ctrl + Shift + b`でサクサクビルドして、画面をF5でサクサク更新！

以下のように表示されます（上：doxygen形式、下：マークダウン形式）

![image-embed.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/927bd2b3-bb52-f474-9aa4-71e0305b2d21.png)

## ドキュメントの中にPlantUMLで図を描く

クラス図などをつくるには、PlantUMLが便利です

### PlantUMLを準備する

[PlantUMLのダウンロードサイト](https://plantuml.com/ja/download)
`plantuml.jar`を任意の場所に置きます。
参考サイトにのっとって、Cドライブ直下に`PlantUML`フォルダーを作成し、ダウンロードした`jar`ファイルを配置します。

DoxygenGUIで指定した様子
![plantuml.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/b956e597-879f-91fc-2b7f-a12219910a39.png)

### PlantUMLを使用する

`page2.md`ファイルに以下を書きます。

``` PowerShell
# ページ2 {#page2}

ここはpage2です

\startuml Title
Hello <|-- World
\enduml
```

VS Code上で`Ctrl + Shift + b`、サクサクビルド！

![plantuml-page.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/33062142-1a90-7642-a6f3-634bc172b86b.png)

マークダウン形式で書くと（```pumlくくると）その部分がコードとして認識されてしまう。

![plantuml-code.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/5c229b52-3488-094e-0c83-4d75873a7a0d.png)

（```puml）でくくらなければ、意図した通りに表示される。

``` PowerShell
@startuml
class ABC
@enduml
```

![plantuml-code2.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/13bc4553-67d4-1fb5-fe81-566c6af393c8.png)

VS Codeでは[Markdown Preview Enhanced](https://shd101wyy.github.io/markdown-preview-enhanced/#/)を使ってプレビューしているので
（```puml）で囲わないとPlantUMLがプレビューされないし
逆に（```puml）で囲ってしまうとdoxygenの方でコードとして解釈されてしまう

VS Codeのプラグインにdoxygen用のプレビューがあればよいのだけれど・・・
そこだけが悩ましい。

## ドキュメントにソースコードへのリンクを貼る

C#ソースコードのクラスにリンクを貼ってみます。

例として、`doxyApp`の`Models`フォルダーに`Class1`をつくりました。

![package.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/d763c66d-23aa-be7a-6adf-b1f91a4ab5b0.png)

インデックスページのドキュメントから`Class1`のコンストラクターへ飛びます。

目的地はココ↓

![class1.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/0e49db4d-21be-1d14-f3c2-f0f0017132f1.png)

インデックスページ

![link-vscode.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/08ce19ee-c5f3-ba0c-445d-a477261ecae8.png)

↓↓↓
doxygenで生成されたページ

![link-doxy.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/272511/c2cd628d-ebec-4a3d-ba21-b0ac481cc646.png)



## おわりに

[doxygenにはその他たくさんのコマンドが用意されています](http://www.doxygen.jp/commands.html)

便利なものは使っていきたいですね！