Doxygenは、コメントブロック内のドキュメントを強化したり構造化したりするために使用できる、多数の特殊コマンド、XMLコマンド、およびHTMLコマンドを提供しています。何らかの理由で新しいコマンドを定義する必要がある場合は、エイリアス定義によってそれを行うことができます。
エイリアスの定義は、ALIASES設定タグを使用して、設定ファイル内で指定する必要があります。
最もシンプルな形式のエイリアスは、以下の形式の単純な置換です。
name=value
例えば、以下のエイリアスを定義すると、
ALIASES += sideeffect="\par Side Effects:^^"
ドキュメントにコマンド\sideeffect（または@sideeffect）を記述できるようになり、副作用:という見出しを持つユーザー定義の段落が生成されます。
エイリアスの値部分に\nを記述しても、(結果として出力される)改行は挿入されないことに注意してください。エイリアスの値部分に^^を記述すると、元のファイルに物理的な改行があったかのように改行を挿入できます。
エイリアスの値部分にリテラルの{、}、または,（あるいはデフォルト以外のセパレータ）が必要な場合は、バックスラッシュ（\）でエスケープする必要があることに注意してください。これはコマンド\{および\}と競合する可能性があり、これらの場合には@{および@}バージョンを使用するか、二重エスケープ（\\{および\\}）を使用することをお勧めします。
また、必要に応じて既存の特殊コマンドを再定義できることにも注意してください。
\xrefitemのような一部のコマンドは、エイリアスと組み合わせて使用するように設計されています。
エイリアスは1つ以上の引数を持つこともできます。エイリアス定義では、中括弧の間に引数の数を指定する必要があります。定義の値部分には\xマーカーを配置でき、ここで'x'は1から始まる引数番号を表します。
以下は、単一の引数を持つエイリアス定義の例です。
ALIASES += l{1}="\ref \1"
コメントブロック内では、以下のように使用できます。
/** See \l{SomeClass} for more information. */
これは次のように記述するのと同じです。
/** See \ref SomeClass for more information. */
例えば、複数の引数を持つバージョンでエイリアスをオーバーロードできることに注意してください。
ALIASES += l{1}="\ref \1"
ALIASES += l{2}="\ref \1 \"\2\""
エイリアス定義内の引用符はバックスラッシュでエスケープする必要があることに注意してください。
これらのエイリアス定義を使用すると、
/** See \l{SomeClass,Some Text} for more information. */
コメントブロック内で記述すると、以下のように展開されます。
/** See \ref SomeClass "Some Text" for more information. */
その際、単一引数のコマンドは以前に示したように引き続き機能します。
エイリアスは、他のエイリアスを使って表現することもできます。例えば、新しいコマンド\reminderは、中間的な\xreflistコマンドを介して、\xrefitemとして以下のように表現できます。
ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}"
複数の引数を持つエイリアスでコンマがセパレータとして使用される場合、コマンド内にコンマを記述したい場合は、バックスラッシュでエスケープする必要があることに注意してください。つまり、
\l{SomeClass,Some text\, with an escaped comma}
上記の例の\lのエイリアス定義を考えると。
デフォルトでは、エイリアスにおける引数のセパレータはコンマです。しかし、関数定義のテンプレートのように多くのコンマを含む引数の場合、それぞれのコンマをエスケープするのは煩わしいことがあります。これを解決するために、パラメータ数の直後に異なるセパレータを指定できます。例えば、セミコロンをセパレータとして使用するには、コマンドを以下のように定義できます。
ALIASES += xreflist{3;}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders;Reminder;Reminders}"
複数の文字からなるセパレータも許可されていることに注意してください。つまり、同じ例を二重パイプ記号をセパレータとして使用して記述できます。
ALIASES += xreflist{3||}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders||Reminder||Reminders}"
セパレータを作成するために以下の文字が許可されています。
!#$%&,.?|;:'+=~`/
各コマンドとパラメータ数ごとに、異なるセパレータを使用できることに注意してください。ただし、同じコマンドに対して異なるセパレータを選択することは推奨されません。これは、どのコマンド定義を使用すべきかについて曖昧さを生じさせる可能性があるためです。Doxygenは、最も多くのパラメータに一致するコマンドを選択することによって、そのような曖昧さを解決します。以下の、やや不自然な例を考えてみましょう。
ALIASES += v{2+}="Choose 2: '\1' and '\2'"
ALIASES += v{3;}="Choose 3: '\1', '\2', and '\3'"
すると、
- \v{One+Two}
- \v{One;Two;Three}
- \v{One+Two;Three;Four}
以下を生成します。
最後のコマンドでは、vの定義は両方とも一致しますが、より多くのパラメータに一致するため、3つのパラメータを持つ方が選択されます。
エイリアスによって定義されたコマンドを含め、コマンドをエイリアスの引数として使用できます。
例として、以下のエイリアス定義を考えてみましょう。
ALIASES += Bold{1}="<b>\1</b>"
ALIASES += Emph{1}="<em>\1</em>"
コメントブロック内では、これで以下のように使用できます。
/** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */
これは以下のように展開されます。
/** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */
1.14.0