Simple aliases

The simplest form of an alias is a simple substitution of the form

 name=value

For example defining the following alias:

 ALIASES += sideeffect="\par Side Effects:^^"

will allow you to put the command \sideeffect (or @sideeffect) in the documentation, which will result in a user-defined paragraph with heading Side Effects:.

Note that you cannot put \n's in the value part of an alias to insert newlines (in the resulting output). You can put ^^ in the value part of an alias to insert a newline as if a physical newline was in the original file.

Note when you need a literal { or } or , (or non default separator) in the value part of an alias you have to escape it by means of a backslash (\), this can lead to conflicts with the commands \{ and \} for these it is advised to use the version @{ and @} or use a double escape (\\{ and \\})

Also note that you can redefine existing special commands if you wish.

Some commands, such as \xrefitem are designed to be used in combination with aliases.

Aliases with arguments

Aliases can also have one or more arguments. In the alias definition you then need to specify the number of arguments between curly braces. In the value part of the definition you can place \x markers, where 'x' represents the argument number starting with 1.

Here is an example of an alias definition with a single argument:

ALIASES += l{1}="\ref \1"

Inside a comment block you can use it as follows

/** See \l{SomeClass} for more information. */

which would be the same as writing

/** See \ref SomeClass for more information. */

Note that you can overload an alias by a version with multiple arguments, for instance:

ALIASES += l{1}="\ref \1"
ALIASES += l{2}="\ref \1 \"\2\""

Note that the quotes inside the alias definition have to be escaped with a backslash.

With these alias definitions, we can write

/** See \l{SomeClass,Some Text} for more information. */

inside the comment block and it will expand to

/** See \ref SomeClass "Some Text" for more information. */

where the command with a single argument would still work as shown before.

Aliases can also be expressed in terms of other aliases, e.g. a new command \reminder can be expressed as a \xrefitem via an intermediate \xreflist command as follows:

ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}"

Note that if for aliases with more than one argument a comma is used as a separator, if you want to put a comma inside the command, you will need to escape it with a backslash, i.e.

\l{SomeClass,Some text\, with an escaped comma}

given the alias definition of \l in the example above.

By default the separator for arguments in an alias is a comma. However, for arguments with a lot of commas, such as templates of function definitions, escaping each comma can be cumbersome. To solve this, one can specify a different separator, directly after the parameter count, for example to use a semicolon as separator one can define the command as follows:

ALIASES += xreflist{3;}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders;Reminder;Reminders}"

Note that also multi-character separators are allowed, i.e. the same example can be written using double pipe symbols as separator:

ALIASES += xreflist{3||}="\xrefitem \1 \"\2\" \"\3\" "
ALIASES += reminder="\xreflist{reminders||Reminder||Reminders}"

The following characters are allowed to create separators:

!#$%&,.?|;:'+=~`/

Note that for each command and number of parameters, one can use a different separator. It is not recommended to select a different separator for same command however, as this may lead to ambiguity as to which command definition is to be used. Doxygen resolves such ambiguity by choosing the command which matches the most parameters. Consider the following, rather contrived example:

ALIASES += v{2+}="Choose 2: '\1' and '\2'"
ALIASES += v{3;}="Choose 3: '\1', '\2', and '\3'"

Then

- \v{One+Two}
- \v{One;Two;Three}
- \v{One+Two;Three;Four}

Will produce:

Choose 2: 'One' and 'Two'
Choose 3: 'One', 'Two', and 'Three'
Choose 3: 'One+Two', 'Three', and 'Four'

For the last command both definitions of v match, but the one with 3 parameters is selected as it matches more parameters.

Nesting custom command

You can use commands as arguments of aliases, including commands defined using aliases.

As an example consider the following alias definitions

ALIASES += Bold{1}="<b>\1</b>"
ALIASES += Emph{1}="<em>\1</em>"

Inside a comment block you can now use:

/** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */

which will expand to

/** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */

Go to the next section or return to the index.

Table of Contents

Simple aliases

Aliases with arguments

Nesting custom command