DoxygenPage.md

ドキュメント自動生成

生成されたドキュメントは https://udonrobo.github.io/UdonLibrary/ で公開されています。

Doxygen を用いてソースコード、マークダウンからドキュメントを自動生成しています。マスターブランチにプッシュがあった場合 GitHub Actions を通じてページが更新されます。ワークフローは .github/workflows/DoxygenPage.yml に定義されており、以下の流れで更新を行います。

flowchart LR

    onpush{{プッシュがあった}} --> DoxygenPageフロー

    subgraph DoxygenPageフロー
        direction LR
        Doxygen/HTMLページを生成 --> ページをgh_pagesブランチにプッシュ
    end

    DoxygenPageフロー --> デプロイフロー

    subgraph デプロイフロー
        gh_pagesブランチのページを公開
    end

Loading

Doxygen コメントの書き方

Doxygen コメントは次のように関数、クラス等の上部に記述します。詳細は Doxygen ドキュメント や、既に記述されているソースコードを参照してください。

/// @brief この関数は何？
/// @param arg この引数は何？
/// @return 何を返す？
int Function(int arg);

ローカル環境で実行

1. Doxygen をインストール

   https://www.doxygen.nl/download.html#latestsrc

   Doxygen コマンドが使用できるようパスを通す必要があります。

2. UdonLibrary ディレクトリで Doxygen を実行

   doxygen Doxyfile

3. ページ が ./docs/DoxygenDist/html に生成されるのでブラウザで開く

   start ./docs/DoxygenDist/html/index.html

   生成物は git に追跡されません。

Doxygen のメリット

完全放置で運用できます。

ソースコード中にドキュメントを記述するため、コードの変更に追従しやすく、最新の情報を提供できます。

クラス一覧、関数一覧、ファイル一覧、変数一覧などを自動生成できます。

クラスの継承関係、関数の呼び出し関係などをグラフで表示できます。

マークダウンファイルもドキュメントとして生成でき、コードブロック等に記述したシンボル名を自動的にソースコードとリンクしてくれます。