Doxygenは、コメントブロック内のドキュメントを強化したり構造化したりするために使用できる、多数の特殊コマンド、XMLコマンド、およびHTMLコマンドを提供します。何らかの理由で新しいコマンドを定義する必要がある場合は、エイリアス定義によってそれを行うことができます。
エイリアスの定義は、ALIASES設定タグを使用して構成ファイルで指定する必要があります。
エイリアスの最もシンプルな形式は、次のような単純な置換です。
name=value
たとえば、次のエイリアスを定義すると
ALIASES += sideeffect="\par Side Effects:^^"
ドキュメントにコマンド\sideeffect（または@sideeffect）を記述できるようになり、Side Effects:という見出しのユーザー定義の段落が生成されます。
エイリアスの値の部分に\nを記述して改行を挿入することはできません（結果の出力に）。エイリアスの値の部分に^^を記述して、物理的な改行が元のファイルにあったかのように改行を挿入できます。
エイリアスの値の部分にリテラルの{または}または,（またはデフォルト以外の区切り文字）が必要な場合は、バックスラッシュ（\\endiskip）でエスケープする必要があります。これは、コマンド\{および\}と競合する可能性があり、これらのコマンドには@{および@}のバージョンを使用するか、二重エスケープ（\\{および\\}）を使用することをお勧めします。
また、必要に応じて既存の特殊コマンドを再定義できることにも注意してください。
\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.15.0 で生成