DoxygenのMarkdownサポート
doxygenでは、次の2つの部分でmarkdownが使える。
- ソースとは別な文書ファイルとして： 拡張子が.mdまたは.markdownであるファイルを、doxygenの処理対象ファイルに含めれば、それはmarkdown文書と解釈されて変換処理がされる。
- ソースコード内の文書コメントとして： 特に何もしなくても、文書コメント内のmarkdownマークアップが認識される。
文書コメント（doxygenでは特殊文書ブロックと呼ぶ）内では、もともとdoxygenコマンドが書けるので、次の3つの構文が混じることになる。
- doxygenコマンドを含むdoxygen構文。コマンドの先頭文字は\と@が許される。doxygenコマンドはJavaDocコマンドの上位互換らしい。
- markdownマークアップ
- HTMLタグがそのまま使える（これはmarkdownの仕様でもある）
混合構文なので、複雑怪奇になり得る。
doxygenによるmarkdown拡張
PHP Markdown Extraの仕様の一部を取り入れているらしい。
- 見出しへのID付けと、見出しへのリンク ： 「### 見出し2 ### {#section-id-2}」のように書けて、[リンクテキスト](#section-id-2) とフラグメントIDで参照するリンクを書ける。これは便利だが、互換性が、、、、
- インデントなしのコードブロック ： GitHubの```ではなくて、~~~（3つ以上の~）。ウーム、これは困った、pandocだと取り消し線になってしまう！ コードの言語の指定も ~~~[.py] のように書く。これも、```py とは違う。
次はdoxygen独自らしいが、同様な拡張をしているmarkdown処理系もある。
markdownでメインページを作る方法
文書コメント（特殊文書ブロック）内に \mainpage（@mainpageでも同じ）コマンドを使うと、そのブロック内容がメインページ内容として使われる。が、メインページを単独の文書ファイルとしたほうが便利だろう。
- メインページになるmarkdown文書を作成する。doxygenがmarkdownだと認識できる拡張子にする。
- その文書の先頭にレベル1の見出し（「# タイトル」など）を付ける。例：README.md
- レベル1の見出し＝タイトルに、{#index}または{#mainpage}というIDを付ける。
これは見出しにIDを付ける機能を流用して特別な用途に使っている。
注意事項やヒント
- インラインのマークアップはあんまりうまく動かない。<em>とか<strong>とか、HTMLタグを使ったほうがいい。
- 文書コメント内では、doxygenコマンドを使うのは問題ない。単独ファイル内では使わない。
- コード範囲（インラインでのコード記述）の`...`は使えるが、コードブロックが困ったな。インデント方式なら互換性保って使えるが、メンドクサイ！
- 複数段落からなる箇条書きが書ける。これはmarkdownオリジナル仕様か。
- テーブルの右寄せ、中央、左寄せが出来る。これもmarkdownオリジナル仕様だったか？
- エスケープ方式が不明、doxygen構文におけるエスケープは、\\と\@。
もうちょい使ってみないと、まだ分からない点が多い。
