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.13.0 によって生成されました