Salesforce Apex Class のドキュメントを Doxygen で生成

Salesforce `Apex Class` のドキュメントは `Doxygen` を使用して生成することが可能です。 `Doxygen` は各種ソースコードからドキュメントを生成するための歴史の長いツールです。そして Apex ソースコードから ちょっとした `Javadoc`似ドキュメントをさくっと生成するときに Doxygen はとても役立ちます。この方法をメモしておきます。

# ソースコードに Javadoc 的コメントを記述

Doxygen をもちいたドキュメント自動生成には、`Javadoc`風コメント記述を利用することができます。Doxygen 自体は様々な言語に対応していますが、このメモでは Doxygen の Java対応機能を Apex用途に流用することによりその恩恵を受けます。ドキュメント生成には所定の前準備が求められ、具体的にはソースコード上に Javadoc風のコメントを記述する必要があります。 Apex は Java言語に文法などが似ているので、ちょうど Javadoc コメントを利用する方法は自然で理にかなっているように感じられます。

具体的には、以下のようなスタイルで Apex (.cls) ソースコードのファイルヘッダ、フィールド、メソッドに `Javadoc`風コメントを記述していきます。

```java
/**
 * メソッドの説明.
 *
 * @param input1 入力値その1.
 * @return 戻り値の説明.
 */
```

ちなみに、もしあなたが vscode を利用しているのであれば、拡張機能から Doxygen 入力支援機能を組み込むことによって、Doxygen記述の生産性を向上させることができることでしょう。

# Doxygen の利用

Doxygen コマンド・ツールのインストールは各種サイトなどで説明がありますのでそれらを参照ください。

なお、macOS で `brew` がインストール済みであれば、以下のコマンドラインにより Doxygen のインストールが実現できます。

```sh
brew install doxygen
```

## Doxyfile を生成

次に用意する必要があるのは `Doxyfile` という Doxygen の挙動を制御する設定ファイルの準備です。
Doxygen を利用するには、利用に先立ち Doxyfile というファイルの存在が前提だからです。

以下のように doxygen コマンドを `-g` オプション付きで呼び出すことにより `Doxyfile` のひな型を生成することができます。

```sh
doxygen -g
```

実行後に、カレントディレクトリに `Doxyfile` というファイルが生成されていることを確認します。

## Doxyfile を編集

生成された `Doxyfile` はひな形記述そのままですので、Apex Class を適切に認識して処理するように Doxyfile を編集します。

### 入出力ディレクトリを指定

まずは、入出力ディレクトリを指定します。
入力ディレクトリのパス指定を環境にあわせて設定します。Salesfoce CLI (sfdx) を利用していると以下のようなフォルダ構成になっているはずです。

```properties
INPUT                  = force-app/main/default/classes
```

出力ディレクトリには、`doxygen-apex` というディレクトリに変更することにします。これは私が勝手に命名した名称です。

```properties
OUTPUT_DIRECTORY       = doxygen-apex
```

### FILE_PATTERNS に .cls を追加

「.cls」拡張子のファイルを doxygen の処理対象に追加します。

```properties
FILE_PATTERNS          = *.cls \
                         *.c \
```

`*.cls \` の記述を追記します。

### .cls を Java にマッピング

「.cls」拡張子のファイルを Java言語として処理するようにマッピングします。

```properties
EXTENSION_MAPPING      = cls=Java
```

### Javadocらしさ設定

```properties
OPTIMIZE_OUTPUT_JAVA   = YES
```

### 展開オプションを変更

展開オプションを必要に応じて更新します。

```properties
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
```

## Doxygen の実行

```sh
doxygen
```

実行が終わると、`doxygen-apex`ディレクトリにドキュメント一式が自動生成されます。
期待していた内容になっているか確認します。

# この手順で出来上がる Doxyfile サンプル

この手順で出来上がる Doxyfile サンプルは以下の github を参照ください。

- https://github.com/igapyon/Doxyfile/tree/devel/Salesforce

# 番外編1: Lightning Web Components (LWC) の JavaScript からドキュメント生成

Lightning Web Components (LWC) の JavaScript からドキュメント生成するには、以下のように `Doxyfile` の設定を更新します。

```properties
INPUT                  = force-app/main/default/classes force-app/main/default/lwc

FILE_PATTERNS          = *.cls \
                         *.js \
                         *.c \
...

EXTENSION_MAPPING      = cls=Java js=JavaScript

RECURSIVE              = YES
```

# 番外編2: Doxygen の MAINPAGE の設定方法

Doxygen の MAINPAGE の設定方法

```properties
INPUT                  = README.md force-app/main/default/classes force-app/main/default/lwc

USE_MDFILE_AS_MAINPAGE = README.md
```

# 追加の知見

- 2022/12/25 : この Doxygen 設定だと `global` スコープのクラスやメソッドなどに対応しません。そもそもクラスが認識されなかったりメソッドが存在しないように処理される不都合が把握できています。

# 環境

この記事は、`Doxygen version 1.9.2` に基づいて記述しました。
初出: 2021-10-27