作成日: 2023.03.22

Doxygen 入門 (Windows編)

Windows 版の Doxygen を使ってソースコードのコメントからドキュメントを生成する方法について調べたことをまとめます。

Python 以外の主要な言語の関数仕様書はDoxygenで生成すると容易です。

公式サイト
https://www.doxygen.nl/

有志による日本語サイト
http://www.doxygen.jp/

インストール

Doxygen で ドキュメント生成する上で必要となるアプリケーションをインストールします。

Doxygen のインストール

https://www.doxygen.nl/download.html より Windows版 の Doxygen（doxygen-1.9.6-setup.exe）をダウンロードしインストールします。
※2023年3月17日現在の最新バージョンは1.9.6。

ダウンロードした.exeをクリックすると、以下のような画面がでますので、赤丸の詳細情報を選択します。

すると実行ができるようになりますので実行します。

セットアップはほぼ標準のままです。Full Installation になっていることを確認してインストールを完了させましょう。

ユーザー環境変数のPathに

"C:\Program Files\doxygen\bin"

を追加しておきましょう。

Graphviz のインストール

Doxygen でも図は書けるみたいですが、 Graphviz と連携するほうがより一般的なようですので、 Graphviz をインストールします。

https://graphviz.org/download/ より graphviz-7.1.0 (64-bit) EXE installer をダウンロードしてインストールします。
※2023年3月17日現在の最新バージョンは7.1.0。ここでは64bit版にしました。

インストールはデフォルトのままで問題ないですが、単体で使えるツールなのでパスも通しておきましょう。

Doxygenと連携して使うには、Doxyfile の DOT_PATH に dot.exe (C:\Program Files\Graphviz\bin\dot.exe) を設定する必要があります。Doxyfileの設定については後述します。

TeX Live のインストール

Doxygen で自動生成できるドキュメントはいわゆるWebページであって、PDFなどのドキュメントではありません。
が、DoxygenはLatexでの出力もできるので、それをPDFに変換すればPDFのドキュメントを作ることができます。
しかしながら、Doxygenに内包されているものだと日本語化ができません。
よって、TeX Live(https://www.tug.org/texlive/) をインストールします。

https://www.tug.org/texlive/acquire-netinstall.html から install-tl-windows.exe をダウンロードしてインストールしましょう・・・と言いたいところですが、なぜか失敗します。原因は不明です。

よって、install-tl-windows.exe ではなく、install-tl.zipをダウンロードして展開、コマンドプロンプトでinstall-tl-windows.batのあるパスに進み、

.\install-tl-windows.bat --no-gui

と実行してインストールする必要がありました。ずいぶんはまってしまいました。

インストールが完了したら、環境変数のpathに、

C:\texlive\2023\bin\windows

を追加しておきましょう。(2024年のやつを入れてみたら2024になってた。当然か)

Ghostscript のインストール

TeX Liveに含まれてるのでいらない、という情報を得て入れてなかったのですがエラーになったので入れることにしました。環境によっては不要かもしれません。

https://www.ghostscript.com/ から インストールしておきましょう。

PlantUML のインストール

PlantUML は java の jarファイルとして提供されていますので、https://plantuml.com/en/download より plantuml.1.2023.4.jar ファイルをダウンロードします。
※2023年3月24日現在において、最新バージョンは Version 1.2023.4 でした。
ダウンロードしたjarは任意のディレクトリに置いておきます。

Doxygenと連携して使うには、Doxyfile の PLANTUML_JAR_PATH に plantuml.1.2023.4.jar のパスを設定する必要があります。Doxyfileの設定については後述します。

jarファイルを実行するにはJREが必要ですので、未インストールの場合はhttps://www.java.com/en/download/よりインストールしパスを通しておきます。
JREが入っているかどうかはコマンドプロンプトで java -version で分かります。

> java -version
java version "1.8.0_361"
Java(TM) SE Runtime Environment (build 1.8.0_361-b09)
Java HotSpot(TM) 64-Bit Server VM (build 25.361-b09, mixed mode)

Doxygen の 設定

一通りインストールが終わったので次は設定を行います。

CLIを使った設定ファイルの生成

設定は Doxyfile という設定ファイルに設定します。

最初は存在していないので、

> doxygen.exe -g

というコマンドで生成します。

なお、"Doxyfile" という名という名称は 設定ファイルのデフォルトの名前ですが、別の名前をつけたいのであれば、

> doxygen.exe -g hoge

と -g の後ろにファイル名を付ければよいです。
ただし、この場合、設定ファイルがデフォルトのファイル名ではなくなったので、ドキュメント生成時(doxygen.exe実行時)に設定ファイルを引数に渡してあげなければなりません。

> doxygen.exe 設定ファイル

設定をDoxyfileとしている場合のみ指定は不要です。

GUIを使った設定ファイルの生成

先ほどはコマンドプロンプトでDoxyfileを設定しました。

が、Doxyfileの中をみてうんざりしたのではないでしょうか？相当な数のパラメーターがあり、何から手をつければ良いかもわかりません。

そんな不満を和らげるべく、GUIを使ってDoxyfileの設定を補助してくれるツールがあります。

doxywizardです。
Doxygen GUI frontend という別称がついていますが、どちらにせよこれらの名前で呼ぶ人はいないでしょう。 たいていの人はDoxygenのGUIのやつと言っているかと思います。

このツールを起動すると直感的に設定をすることができるようになります。
(そうはいっても説明不足な感は否めないですが、ないよりはるかにましです）

ここではdoxywizardを使って値を設定していきます。
ただし、デフォルトの状態のDoxyfileは別途コピーするなりしてバックアップしておきましょう。
あとで diff をとることで、CLIでDoxyfileの設定したい場合はここを直接変更すれば良いのか！という参考になりますので。

doxywizard.exe は doxygen.exe同様、C:\Program Files\doxygen\bin配下にありますのでパスを通していれば doxywizard で起動します。
(コマンドプロンプトでもよいし、直接ダブルクリックしてもよいし、検索窓に入力しても良いです)

GUIを使った設定ファイルの値変更

ではGUIでDoxyfileを作っていきましょう。

まずは起動です。

一番上の四角のところに作業ディレクトリを指定しましょう。
Doxygen が作業に用いるテンポラリーディレクトリです。
デフォルトではDoxyfileはこのディレクトリ直下に置きます。
source code directoryやdestination directoryを個別に指定しない場合、全部ここが起点になります。
そのため、ソースコードのあるディレクトリとは分けたほうが見やすさ的に無難かと思います。

Project Nameは任意の名前を付けましょう。日本語でも問題ないです。
(実際は文字化けしますが、文字化けしない対応をするので）
Source code directory:にはソースコードをおいているディレクトリを指定しましょう。
Scan recursivelyにチェックを入れないと再帰的にファイルを検索してくれないので必要に応じてチェックを入れます。
Destination directoryにパスを指定しない場合、working directoryに出力されます。あえて指定する必要はないと思います。

Wizardタブの中のModeを選択します。
Documented entities onlyを選択するとDoxygen用のコメントが書かれているソースしか基本的にはドキュメント化されません。 All EntitiesにするとDoxygenがコメントのないものも含めすべてのソースを解析しようとします。
そのため意図しないドキュメントができる可能性がありますが、便利ではあります。
必要に応じて切り替えましょう。
Include cross-referenced source code in the output
は相互参照をしているコードを関連付けてドキュメント出力してくれるそうですが、つけてもつけなくても変わらずよくわかりません。

Select programming language to optimise the results for: は解析対象のソースの言語を選択してください。

次はOutputですがデフォルトのままで問題ないです。

Diagramsでは GraphVizを使うのでラジオボタンを Use dot tool from the GraphVix package にしないといけません。
Call graps と Called by graphs はチェックをつけてもつけなくてもあんまり変わりませんでした。

では設定はとりあえずできましたので、DoxyfileをSaveしましょう。保存しないと、次のRun doxygenボタンが disableになって押せません。

保存したらソースも何もないですが、ドキュメントを生成してみましょう。

Runタブを選択し、Run doxygenボタンを押下します。

これでhtmlができました。working directory内にhtmlというディレクトリができますのでindex.htmlをクリックするとドキュメントがブラウザに表示されます。
が、GUIの Show HTML output を押しても同様に表示されますので押してみましょう。

出来上がりのhtmlがこんな感じです。

設定だけをしたきわめてシンプルなDoxygenによるドキュメントが完成しました。

CLIを使った設定ファイルの値変更

先ほどGUIで変更しましたが、これをCLIでやりたい場合、以下を変更すれば同様になります。

Doxyfileをviなどで開き、

INPUT                  =
->
INPUT                  = C:/Users/ユーザ名/Documents/source


RECURSIVE              = NO
->
RECURSIVE              = YES


HAVE_DOT               = NO
->
HAVE_DOT               = YES


CALL_GRAPH             = NO
CALLER_GRAPH           = NO
->
CALL_GRAPH             = YES
CALLER_GRAPH           = YES

と変更するだけです。
これで先ほどのGUIでやった操作と同じことができます。
慣れると直接編集するほうが容易でしょう。が、最初はどれを触ればよいかさっぱりかと思いますのでGUIでやるのがよいかと思います。

関数仕様書の作成

Doxygenはソースコードにコメントを書くことでドキュメントを作ってくれますが、「何の」ドキュメントを作ってくれるのでしょうか？

その問いの答えは難しく、一見、関数仕様書を作成してくれるツールかな？と思われがちですが、PlantUMLをつかってシーケンス図を書いたりもできますし、レイアウトファイルを使ってタブを任意に増やして、そこにmarkdownで書いた文書を表示したりもできるますので、「何の」というより「何でも」作れる感じではあります。

が、まぁ基本は関数(クラス)仕様書です。

ので、とりあえずですが、C++言語で作られた簡単なコードをつかってドキュメントを生成してみましょう。

以下の3つのクラスのサンプルコードを準備します。
C++ですのでmain()を呼び出すコードも必要ですが(main.cppのような)、ドキュメント生成に関してはいらないので不要です。
もっというと、コメントが書いてあるほうのファイル(ヘッダにコメントを書くならヘッダファイル)だけでよいです。

diagrams_a.h

#ifndef DIAGRAMS_A_H
#define DIAGRAMS_A_H
/**
 * @brief 加算と減算の機能を提供するクラス
 */
class A {
public:
    /**
     * @brief コンストラクタ
     */
    A();

    /**
     * @brief デストラクタ
     */
    ~A();

    /**
     * @brief 加算関数。第一引数に第二引数を加算した値を返却する
     * @param a 加算される値
     * @param b 加算する値
     * @return aとbの加算結果
     */
    int add(int a, int b);

    /**
     * @brief 減算関数。第一引数から第二引数を減算した値を返却する
     * @param a 減算される値
     * @param b 減算する値
     * @return aとbの減算結果
     */
    int subtraction(int a, int b);
};
#endif

diagrams_b.h

#ifndef DIAGRAMS_B_H
#define DIAGRAMS_B_H
#include "diagrams_a.h"

class A;

/**
 * @brief クラスAの加算と減算の機能を用い、加算と減算を同時に行う機能を提供するクラス
 */
class B {
public:
    /**
     * @brief コンストラクタ
     */
    B();

    /**
     * @brief デストラクタ
     */
    ~B();

    /**
     * @brief 加算と減算関数。Class Aのaddとsubtractionを用いて第一引数に第二引数を加算したのち第三引数を減算する
     * @param a 加算と減算される値
     * @param b 加算する値
     * @param c 減算する値
     * @return aとbの加算結果
     */
    int add_subtraction(int a, int b, int c);

private:
    A* m_a; ///< Class Aのインスタンス
};
#endif

diagrams_c.h

#ifndef DIAGRAMS_C_H
#define DIAGRAMS_C_H
#include "diagrams_a.h"

/**
 * @brief 乗算と除算の機能を提供するクラス。加算と減算をするクラスAを継承し、加減乗除すべての機能を提供する
 */
class C : public A {
public:
    /**
     * @brief コンストラクタ
     */
    C();

    /**
     * @brief デストラクタ
     */
    ~C();

    /**
     * @brief 乗算関数。第一引数に第二引数を乗算した値を返却する
     * @param a 乗算される値
     * @param b 乗算する値
     * @return aとbの乗算結果
     */
    int multiplication(int a, int b);

    /**
     * @brief 除算関数。第一引数から第二引数を除算した値を返却する
     * @param a 除算される値
     * @param b 除算する値
     * @return aとbの除算結果
     */
    int division(int a, int b);
};
#endif

これらを作成し、自身で設定したソースディレクトリ配下に配置しましょう。

では次にGUIで以下のように設定をします。

Expertタブを開き、Projectを選択しましょう。
プロジェクト名を設定し、OUTPUT_LANGUAGEをJapaneseにします。
プロジェクト名は日本語で問題ありません。

次に、Buildを選択します。

EXTRACT_ALLにチェックを入れるとDoxygenコメントが入っていないドキュメントも文書化の対象になります。
最初の Wizard の Mode で Documented entities only を選択しましたのでチェックは入っていません。
これをAll Entitiesにした場合はチェックが入っています。要は同じ設定なんですね。
Doxyfileを開けばどちらを変更してもどちらも同じ個所が変更されます。
必要に応じて切り替えましょう。今回は外します。

その下の、 EXTRACT_PRIVATE にチェックを入れるとprivate関数もドキュメント対象にされます。
また、 EXTRACT_STATIC にチェックを入れるとstatic関数もドキュメント対象になります。
これらも必要に応じてつけたりつけなかったりしましょう。

次に、Inputを選択します。 INPUTはソースコードのあるディレクトリを指定します。
すでにWizardのProjectのSouce code directoryで指定していますので値が入っています。
RECURSICVE も同様で、Scan recursivelyにチェックを入れたのでチェックが入っています。

次はLaTeX（ラテフまたはラテックと読むんだって。ラテックスって読んでた）です。

GENERATE_LATEXにチェックが入っていないとlatexは作られないのでチェックを入れましょう（デフォルトで入っています)
LATEX_CMD_NAMEには uplatex.exe を指定します。
これはTeX Liveをデフォルトのインストール先にインストールしたのであれば、C:\texlive\2023\bin\windows\uplatex.exe にあるはずです。
(2024年とか新しくなれば当然ディレクトリ名も2024とかになるので注意)
ただし、環境変数にパスを通していたら uplatex.exe(またはuplatex)とだけ入力しても問題ありません。

また、USE_PDFLATEXのチェックは外しましょう。
これはDoxygenのLaTeX機能を使うときにチェックを入れるのであって、TeX Liveを使う場合はいらないので外します。(ただつけてもつけなくても結果に影響はなかったけど)

最後はDotです。
まずHAVE_DOTにチェックがついていることを確認します。
これは別途インストールしたGraphvizを使うことを示します。
最初のWizardのDiagramsで Use dot tool from the GraphViz packege のラジオボタンを選択していたらチェックがついているはずです。
ついていなければつけましょう。

次に UML_LOOK にチェックを入れます。
これにチェックを入れると継承図（コラボレーション図）を生成してくれます。
いらなければつけなくてよいです。

CALL_GRAPHとCALLER_GRAPHにチェックが入っているとソースコードを調べて呼び出し元とかを関係図を生成します。
(単に疑問だけれど、ソースコードを解析するのってコンパイラとかないと大変だと思うのだけど、Doxygenはどうやって解析してるんだろう？)

少し下のほうに下がって、まだ使わないですがついでに PLANTUML_JAR_PATH に PlantUML の インストールでダウンロードした、 plantuml-1.2023.4.jar のフルパスを指定しておきます。
このjarファイルはダウンロードして任意の場所に置いたかと思いますのでそこのパスを指定しましょう。
これはコメントにPlantUML記法でシーケンス図などを書いていたらそれを図示してくれるものなのでまだ使いません。

ここまで終わればRun Doxygenボタンを押せばドキュメントの生成が完了です。

ドキュメントが生成されたら Show HTML output ボタンを押せば、

ブラウザにドキュメントが表示されます。

とりあえずですがシンプルな関数ドキュメントが生成されました。

次はPDFを作成します。

HTMLをPDF文書に変換

Doxygenの文書はHTML形式なので納品物としては好ましくありません。
（まぁ最近はhtmlでもいいけどな的なところもありますが）

紙に印刷できる形じゃなきゃダメ！的な古臭いところもあります。

たとえば公官庁などは設計としてのドキュメントが必要なのではなくて、納品物としてのドキュメントが必要なので、印刷できない形式はNGですね。
(そのうち河野太郎さんが誰かがハンコを減らしたように変えていってくれるとは思いますが)

よって、htmlの文書をpdfに変換しなければなりません。
変換には ダイレクトに html から pdf にするのではなく、間に LaTeX をはさみます。
そう、なんかわからんとLaTeXの設定をしていたのはこのPDF化のためだったんですね。

Run Doxygen した結果、htmlディレクトリだけじゃなくlatexディレクトリができていると思います。
コマンドプロンプトで latex ディレクトリ配下に移動し、

> ./make.bat

と実行します。 ./ をつけないとエラーになるので注意ましょう。

latex>../../../../texlive/2024/bin/windows/uplatex.exe refman.tex
'..' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

みたいなエラーが出たら、LATEX_CMD_NAMEを見直しましょう。相対パスだとダメです。C:/texlive/2023/bin/windows/uplatex.exeと、C:/で始まるようにしておかないといけません。

・・・おや？止まってしまいましたね。

とりあえず Enterキーを押しつづけて最後まで終了しましょう。
すると、refman.pdfというPDFファイルができているはずです。

なぜ止まってしまったのでしょうか？
それは、refman.tex内の

  \usepackage{newunicodechar}
  \newunicodechar{?}{${}^{-}$}% Superscript minus
  \newunicodechar{2}{${}^{2}$}% Superscript two
  \newunicodechar{3}{${}^{3}$}% Superscript three

が悪さをしていたからです。
ので、ざっくり削除しましょう(refman.texはRun Doxygenするたびに再生成されるので、いちいちバックアップとったりせずサクッと消しましょう）

そしてもう一度make.batしてみると、、、今度は止まらずに refman.pdf が生成されました！
やったね！！

では、早速開いてみましょう。

？？？

困りましたね、文字化けしてます。
でも大丈夫です、以下のコマンドを実行すれば日本語化しますので。
（pdfが上書きされるので開いていたら閉じましょう）

> dvipdfmx refman.dvi

を実行後、もう一度PDFを開くと、

やりました！
日本語がばっちり表示されています。

・・・あれれ？でもリンクをクリックしてもページジャンプしないぞ？
そうなんです。上記のコマンドをたたくとハイパーリンクがなくなってしまいます。
ので、以下を実行しましょう。

> ps2pdf refman.ps

これでハイパーリンクは有効になった、、、のですが今度は「しおり」が文字化けしてしまっています！

まったく、困ったものですな。 これは、Ghostscript のバグだそうで未だに直っていないというか誰も直す気なさそうです。
そのため、以下のような回避策が提案されています。

resman.tex の % Hyperlinks の一番下、　% Custom commands used by the header の一行上あたりに、

  \usepackage{pxjahyper}

を追記してください。

pxjahyper は TeX Liveに含まれているので別途インストールとかは不要です。

以下の★のところですね。

  % Hyperlinks
    % Hyperlinks (required, but should be loaded last)
    \ifpdf
      \usepackage[pdftex,pagebackref=true]{hyperref}
    \else
      \ifxetex
        \usepackage[pagebackref=true]{hyperref}
      \else
        \usepackage[ps2pdf,pagebackref=true]{hyperref}
      \fi
    \fi
    \hypersetup{%
      colorlinks=true,%
      linkcolor=blue,%
      citecolor=blue,%
      unicode,%
      pdftitle={サンプル プロジェクト},%
      pdfsubject={}%
    }
  \usepackage{pxjahyper}　＜＝　★ここですね！！！！
  % Custom commands used by the header

そしてもう一度make.batをすると、なんということでしょう、

しおりの文字化けも直りました！！

ただ上述しましたが、refman.texはdoxygenを実行するたびに自動生成で上書きされるわけです。

そのため、毎回毎回毎回毎回上記の書き換えをしなければならず正直しんどいです。
sedとか使ってごにょごにょしてもいいのですが、以下のように割り切るほうがよいかと思います。

・make.batが止まってしまう問題は、Enterキーを押すことで良しとする。

別にEnterキー押すぐらい大した手間じゃないでしょ？毎回 refman.tex 書き換える手間考えたら。

・しおりはとりあえず文字化けさせとく。

開発中は「しおり」が文字化けしたところで大して影響ない。ので開発中は無視し、納品前に限り、上記の pxjahyper による対策を入れてPDF出力するようにすれば、納品前の1回だけの手間で済む。

という感じです。

以上で日本語PDF文書が完成しました！

Doxygen の コメント

Doxygenのコメントは幾つか書き方がありますが、基本的には以下のパターンがいろんな言語的に無難です。

/**
 * ここに書く
 */

/*!
 * ここに書く
 */

とか、!を使うのもありますが、別にどっちでもいいならあえて!を使う必要はないと思うんですね。

あと、コマンドの先頭に @ と \ のどっちを使うのか？もあります。
が、基本 @ にしとけばいいと思います。

/**
 * @brief コメント
 */

\ でも全く同じことなのですが、

/**
 * \brief コメント
 */

このタイプの書き方で書いてる人を私はあまり見かけません。
恐らくなんかの言語でコメント内での @ が意味をもち使うことができない、とかの時のために \ でもいいよ、というDoxygenの対応だと思うのですが、C系やJavaなど主要言語で問題ない/** */ と @ で良いと思います。

いろんな書き方ができるせいで結局どう書けばいいのかよくわからん的な感じになるのは本末転倒ですね。

よく使うコマンドは以下です。

@brief 説明
@param 引数
@return 戻り値

これ書いとけばまぁいい感じになります。
慣れてきたら少しづつ増やしていけばいいと思います。

以下に使えるコマンドのリストがあります。たくさんありますが、現実に使うのは数種類です。
http://www.doxygen.jp/commands.html

面白いのでいえば @bug があります。
上記サンプルのクラスAのadd関数に@bugを追加してみましょう。

    /**
     * @brief 加算関数。第一引数に第二引数を加算した値を返却する
     * @param a 加算される値
     * @param b 加算する値
     * @return aとbの加算結果
     * 
     * @bug バグがあるよ！
     */
    int add(int a, int b);

何が面白いのかというと勝手にRelated Pagesというタブが増えて、そこにリストができるのです。

クリックすると、

とバグのリストが出ます。
同様なものに @todo があります。

ただまぁ、Doxygenでバグ管理やToDo管理をすることは現実にはないと思うので、便利機能ではありますが使うことはないように思います。

コメントはヘッダに書くべきかソースに書くべきか

コメントはヘッダに書くべきでしょうか？それともソースに書くべきでしょうか？
これに関しては開発現場でのルール次第としか言いようがないです。

どっちに書いても問題なくドキュメントは生成されます。
試しに両方に書いてみたところ、同じ内容だと重複せず片方だけが出力されます。
が、それぞれ「別の」内容のコメントを書いてみたところ、それぞれがその分出力されました。

個人的にはソースに書くのが好きです。
例えば上記で説明した @bug (とか他にも @todo とかありますが）は、本来はヘッダではなくソースに書いたほうがよいように思います。
ソースコードの中身を見ながらコメントを書きますし、ソースの変更時についでにコメントも修正、という感じでできますので。
あとPythonのようにそもそもヘッダファイルがない言語もありますし。

ただまぁバグ管理やToDo管理は別でやっているでしょうし(Doxygenでバグ管理してるプロジェクト見たことねぇでげす）、やはり現場次第でしょうか。

Main Pageに何か出したい

htmlを出力してみて思うのは、Main Pageになんもないことです。

ここになんか書いたりするにはどうしたらよいのでしょうか？

Main Pageに書きたいだけなら非常にシンプルで、ソースコードを置くディレクトリ上にmain.doxというファイル(名前はmainじゃなくても良いけど拡張子はdoxで)を作り、そこにDoxygen記法でドキュメントを書けば書いた内容がMain Pageに表示されます。

main.dox

/**

@mainpage   main       メインページだよ！

@section    section    セクションだよ！

@subsection subsection サブセクションだよ！

*/

で、Run Doxygenして表示してみると、

アババ、文字化け。

Shift_JISで書いたせいですね。UTF-8で保存しなおしたら直りました。

@mainpage とか @section とか @subsection はコマンドと呼ばれるものです。
コマンドの記述形式は、

@command name title

となります。

@mainpageコマンドは本文書のメインのタイトルを表示するコマンドです。
一つ飛ばしてtitleは、 画面上部に"メインページだよ！" が表示されていることからわかるかと思いますが、titleに書かれた文字がメインタイトルとして表示されます。
では真ん中の name(ここでは main)は何でしょうか？
これはDoxygenのドキュメントではnameとされていますが、実際には、索引(indexi)だと思ってください。
例えば @ref main と記述すると、@mainpage の場所に飛ぶリンクが自動生成されます。

@sectionは章で、@subsectionは節で、とフォントとかが小さくなっていきます。
さらに@subsubsectionとsubを増やした項がありますが、@subsubsubsection（以降)は存在しません。

@mainpage            main                メインページだよ！
@section             section             セクションだよ！！
@subsection          subsection          サブセクションだよ！！！
@subsubsection       subsubsection       サブサブセクションだよ！！！！
@subsubsubsection    subsubsubsection    サブサブサブセクション...？

このように、subsubsubsectionというコマンドは存在しないのでそのまま文字列が表示されてしまっています。
これより小さいセクションは作れないようです（何か裏技とかあるかもしれないですが）

それはそうと、どうせなら、
1.
1-1.
1-1-1.
みたいな感じで章番号を振ってほしいですよね？
結論を言えばできません。
ただ、PDF化した場合には勝手に番号が割り振られます。

一見便利ですが、HTMLではつかないので、例えば、HTMLで項番を表示したいからと手で以下のように直書きした場合、

@mainpage            main                メインページだよ！
@section             section             1.セクションだよ！！
@subsection          subsection          1-1.サブセクションだよ！！！
@subsubsection       subsubsection       1-2.サブサブセクションだよ！！！！

HTMLでの表示は以下の通り想定通りですが、

PDFは無駄に重複された変な値になります。

ので、どっちにもつけるか、どっちにもつけないかで統一してくれないかなぁ、と思いました。

目次を出したい

目次というよりもナビゲーターでしょうか？一覧を出してリンクでそこに飛ぶ、みたいな目次を画面の右側にぴよっと自動生成することができます。
@mainpage配下に、

@mainpage

[TOC]

...

と[TOC]と書いておくだけです。
あとはsection(subsectionとかsubsubsectionとかも）を目次にしてくれます。

便利！

シーケンス図を書きたい

Doxygenでシーケンス図を描く方法はいろいろありますが、メジャーなのは Mermaid か PlantUMLで、ここではPlantUMLを用います。

PlantUMLを使うには、 PLANTUML_JAR_PATH に plantuml-1.2023.4.jar のフルパスを設定しておかなければいけませんが、すでにしているはずです。

そして以下のように記述すると、

@startuml
    "ユーザ"  ->  "自販機": お金を入れる
    "ユーザ"  ->  "自販機": 商品を選ぶ
    "ユーザ"  <-- "自販機": 商品を出す
    alt おつりがある場合
      "ユーザ"  <-- "自販機": おつりを出す
    end
@enduml

という感じで簡単にシーケンス図が表示される。

PlantUML の 記法

PlantUML の詳しい記法については、https://plantuml.com/ja/guide に日本語でわかりやすく説明がありますので参照しましょう。

改行をしたい

HTMLなので<br>と書けば改行されるのですが、マークダウン記法でよく見られる半角スペース2個 でも改行します。

水平線を出したい

HTMLなので<hr>と書けば水平線が表示されるのですが、マークダウン記法でよく見られるハイフン3つ --- でも水平線が表示されます。

任意のタブの追加

Main Pageだけじゃなく、もっと別のページを追加していったりしたい！とか思うかと思います。
そのような個別のレイアウトをDoxygenでは指定できます。
ただなんかまぁ面倒です。

名称はデフォルトでは DoxygenLayout.xml という名称になります。別の名前を使うなら、そのファイルを Build の LAYOUT_FILE に設定します。
(デフォルトの名称だと勝手に読んでくれます。まぁどちらにせよ設定しておくのが無難かもしれませんね)

<doxygenlayout version="1.0">
  <navindex>
    <tab type="mainpage" visible="yes" title="Main Page"/>
    <tab type="user"     visible="yes" title="Sub Page"  url="@ref subpage"/>

    <tab type="pages" visible="yes" title="" intro=""/>

    <tab type="modules" visible="yes" title="" intro=""/>
    <tab type="namespaces" visible="yes" title="">
      <tab type="namespacelist" visible="yes" title="" intro=""/>
      <tab type="namespacemembers" visible="yes" title="" intro=""/>
    </tab>

    <tab type="classes" visible="yes" title="">
      <tab type="classlist" visible="yes" title="" intro=""/>
      <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> 
      <tab type="hierarchy" visible="yes" title="" intro=""/>
      <tab type="classmembers" visible="yes" title="" intro=""/>
    </tab>

    <tab type="files" visible="yes" title="">
      <tab type="filelist" visible="yes" title="" intro=""/>
      <tab type="globals" visible="yes" title="" intro=""/>
    </tab>
  </navindex>
</doxygenlayout>

これで、自作のSub Page(subpage.dox)が新規タブで表示されます。やったね！

subpage.doxはその中で、@page subpage としておくことで @ref できるようになります。
ファイル名を見てるわけじゃないので注意しましょう。

困ったところ

doxygen.exe や doxywizard.exe をクリックしても起動しない

Windows の 検索窓 で doxywizard を入力し、出てきた doxywizard を起動しようとしても起動しませんでした。

管理者で実行してもダメで、どうしたものかとずいぶん悩んだのですが、ファイルの場所を開く、でファイルの場所を開いたら原因がわかりました。

cygwin の ほうにもdoxygenがあり、そっちのdoxywizard.exeをキックしていたようです。

こちらのdoxywizard.exeはダブルクリックしても何も反応しません。

正しくはインストールパス次第ですが、 C:\Program Files\doxygen\bin 配下に doxywizard.exe があるのでこれをクリックするようにしましょう。
doxygen.exeも同様です。
cygwinのパスよりも上位に来るように環境変数を変更しておくことも大事です。
(ただ、Doxygenを再インストールしたときにPATHの設定し直しをしなかったのでまた起きてしまいました。cygwin上のdoxygenを削除したほうが無難でしょうね。使わないなら）

随分と悩みました。

いくら頑張っても日本語PDFが出力できない

最初、MiKTeXを使って何とかしようとしていました。これを使っても日本語PDF化はできる人はできるのでしょうけど、自分はうまくいかず、結局諦めて、 TeX Live にしたらスムーズに行きました。
(その際、MiKTeXのパスを通したままだったのでかなり混乱しましたが。しっかりアンインストールしないとダメですね)

PDF化したドキュメントに勝手に章番号が連番がつく

PDF化した際に勝手に1.1-みたいな連番が振られてしまいました。
もちろん、それが便利、という意見もあるとは思いますが、任意の番号を付けたい場合に困ってしまうま。
これの対処方法は今のところ分からないです。

<BR>や<HR>がタグのまま表示される

Doxygen記法の場合、改行<br>とか水平線<hr>を記述した場合、本来なら、ちゃんと改行になったり水平線になったりするのですが、時々、そのまま<br>と表示されることがあり困りました。
理由はよくわからないのですが、htmlフォルダを削除して再生成をしたら直ったので、なんかキャッシュ的に悪さでもしてたのかなぁ、という感じです。

PlantUML の画像が表示されない

これはWindows 固有の問題かもしれませんが、日本語のディレクトリ配下で作業すると PlantUML がうまく png を生成できないことがあるようです。
(理由はわからないですが、うまくいくこともあります)

もしシーケンス図の画像がうまく表示されない場合は、日本語ディレクトリか否かを確認し、もし日本語ディレクトリであれば英語に変更しましょう。

ghostscript Error: /undefined in H.S

なんか知らんけど、Doxygenのバージョン上げたらlatexでpdf作るときにエラーがでてどうしようもなく困った。
Ver 1.9.6に戻したら問題なくなった。困ったね。

以上です。