[Doxygen] @page の名前には小文字を使おう

Doxygen の page コマンドの説明によると 「ページへの参照となる <名前> には、 すべて小文字 (mypage1 など) を使用するべきです」とあります。

iutest のドキュメントは GitHub Pages で公開しているのですが、この注意点を知らず 

/**
 * @page    CMDLINE     コマンドラインオプション
 * @par     Command Line Options

のように大文字を使っていました。

ただ、大文字でも特に問題なくドキュメントの生成はできますし、特に問題なく使えていると思っていました。

しかし、実は問題があったのでこの記事を書いているわけです。

名前を大文字にした場合のファイル名が問題だった

@page の名前を大文字にすると、アンダーバー(_) + 小文字に変換されて html ファイルが出力されます。

そして GitHub Pages ではデフォルトで jekyll が有効になっており、アンダーバー(_) で始まるファイルが URL 指定で直接開けず 404 になってしまっていました。。。

対処方法

アンダーバー(_)始まりのファイル名を修正する

Doxyfile の設定で CASE_SENSE_NAMES を YES にすると、文字の変換をせずそのままの名前で出力されるようです。

ただし、大文字小文字を区別しないファイルシステムでは問題になる場合があるので、ドキュメントが推奨するように全部小文字にするのが良さそうです。

GitHub Pages の jekyll を Disable にする

jekyll を無効にすればアンダーバー(_)始まりのファイルでも開けるようになります。

方法はこちらを参考にしてください。 GitHub ioでjekyllをdisableにする - adragoonaの日記

「.nojekyll」ファイルをルートに commit すれば ok です。

結果

今回は前者の方法で対応しました。

ちゃんとアクセスできるようになりましたね。