# Doxygen における画像の仕様

Doxygen 1.14.0 を使用した実験、および Doxygen ソースコード (`src/doxygen.cpp`, `src/docparser.cpp`, `src/docnode.cpp`) の調査に基づく仕様をまとめます。

# 1 IMAGE_PATH の設定

画像を HTML 出力に含めるには、Doxyfile で `IMAGE_PATH` を設定します。

    IMAGE_PATH = path/to/dir

Doxygen を実行するディレクトリからの相対パス、または絶対パスで指定します。

## 1.1 再帰探索

`RECURSIVE = YES` が設定されている場合、`IMAGE_PATH` で指定したディレクトリは再帰的に検索されます。画像が深いサブディレクトリにある場合でも、共通の親ディレクトリを一つ指定するだけで十分です。

    IMAGE_PATH = ./src
    RECURSIVE  = YES

`INPUT` と同じディレクトリを `IMAGE_PATH` に指定するのが確実です。

# 2 コピーされる画像の条件

Markdown から参照された画像のみが HTML 出力ディレクトリにコピーされます。

`IMAGE_PATH` に画像ファイルを配置しても、Markdown から参照されていなければコピーされません。

状況 | コピーされるか
--- | ---
Markdown で `![...](filename.png)` と参照している | ✅ コピーされる
`IMAGE_PATH` に置いているが Markdown から未参照 | ❌ コピーされない

## 2.1 コピー対象の拡張子

Doxygen のソースコードに拡張子フィルタは存在しません。

`src/doxygen.cpp` の `adjustConfiguration()` では、IMAGE_PATH のディレクトリを `readFileOrDirectory()` でスキャンする際に `patList=nullptr` を渡しており、すべてのファイルが `imageNameLinkedMap` に登録されます。Markdown から参照されたファイルをコピーする `findAndCopyImage()` にも拡張子チェックはありません。

    (Doxygen ソースコード: src/doxygen.cpp / adjustConfiguration())
    readFileOrDirectory(path,
        Doxygen::imageNameLinkedMap,
        nullptr,   // exclSet
        nullptr,   // patList  ← 拡張子フィルタなし
        ...

つまり、Markdown から参照したファイルは拡張子に関係なくコピーされます。

HTML での表示はブラウザに依存します。公式ドキュメントの `\image` コマンドには次の記載があります。

> “The image format for HTML is limited to what your browser supports.”
> “Doxygen does not check if the image is in the correct format.”

> — Doxygen: Special Commands —

HTML 出力での実用的な対応形式は以下の通りです。

拡張子 | HTML 出力での扱い | ブラウザでの表示
--- | --- | ---
`.png` | `<img>` タグ | ✅
`.jpg` / `.jpeg` | `<img>` タグ | ✅
`.gif` | `<img>` タグ | ✅
`.webp` | `<img>` タグ | ✅ (主要ブラウザ)
`.svg` | `<object type="image/svg+xml">` タグ | ✅
その他 | `<img>` タグ | ブラウザ依存

`.svg` のみ、Doxygen ソースコード内の `DocImage::isSVG()` (`src/docnode.cpp`) が拡張子を判定して `<object>` タグに切り替えます。

    <!-- SVG の場合 -->
    <object type="image/svg+xml" data="sample.svg" style="pointer-events: none;"></object>

    <!-- それ以外の場合 -->
    <img src="sample.png" alt=""/>

# 3 Markdown からの参照記法と VS Code プレビューとの共存

VS Code のプレビューでは、Markdown ファイルから画像を相対パスで参照する必要があります。

    ![キャプション](images/diagram.png)

この記法を使った場合の Doxygen の動作を確認します。

- Doxygen は `IMAGE_PATH` を再帰的に検索してファイル名 (`diagram.png`) のみで照合する
- 見つかった画像を HTML 出力ルートにフラットにコピーする
- HTML には `<img src="diagram.png">` とファイル名のみを出力する (パスが置き換えられる)

    Markdown の記述:   images/diagram.png
    ↓
    HTML の出力:       <img src="diagram.png">
    コピー先:          docs/doxygen/diagram.png (フラット)

この置き換えにより、VS Code プレビューと Doxygen HTML の両方で画像が表示されます。

環境 | パスの解決 | 結果
--- | --- | ---
VS Code プレビュー | `images/diagram.png` (相対パス) | ✅ 表示される
Doxygen HTML | `diagram.png` (ファイル名のみ) | ✅ 表示される

## 3.1 注意点

異なるディレクトリに同名の画像ファイルが存在する場合、Doxygen は以下の警告を出し、どちらか一方のみをコピーします (ファイル名のユニーク化は行われません)。

    warning: image file name 'images/duplicate.png' is ambiguous.
      /path/to/dir1/images/duplicate.png
      /path/to/dir2/images/duplicate.png

ドキュメントセットが意図した出力になるためには、画像ファイル名がプロジェクト全体で一意であることが必要です。
本フレームワークでは、同名画像ファイルの警告を検出した場合、`make doxy` にて失敗します。これにより、CI/CD で問題を発見、対処できます。