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風コメントを記述していきます。

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

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

Doxygen の利用

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

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

brew install doxygen

Doxyfile を生成

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

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

doxygen -g

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

Doxyfile を編集

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

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

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

INPUT                  = force-app/main/default/classes

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

OUTPUT_DIRECTORY       = doxygen-apex

FILE_PATTERNS に .cls を追加

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

FILE_PATTERNS          = *.cls \
                         *.c \

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

.cls を Java にマッピング

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

EXTENSION_MAPPING      = cls=Java

Javadocらしさ設定

OPTIMIZE_OUTPUT_JAVA   = YES

展開オプションを変更

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

EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES

Doxygen の実行

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 の設定を更新します。

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 の設定方法

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