|
Packit Service |
50c9f2 |
/******************************************************************************
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Copyright (C) 1997-2015 by Dimitri van Heesch.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Permission to use, copy, modify, and distribute this software and its
|
|
Packit Service |
50c9f2 |
* documentation under the terms of the GNU General Public License is hereby
|
|
Packit Service |
50c9f2 |
* granted. No representations are made about the suitability of this software
|
|
Packit Service |
50c9f2 |
* for any purpose. It is provided "as is" without express or implied warranty.
|
|
Packit Service |
50c9f2 |
* See the GNU General Public License for more details.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
* Documents produced by Doxygen are derivative works derived from the
|
|
Packit Service |
50c9f2 |
* input used in their production; they are not affected by this license.
|
|
Packit Service |
50c9f2 |
*
|
|
Packit Service |
50c9f2 |
*/
|
|
Packit Service |
50c9f2 |
/*! \page custcmd Custom Commands
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\tableofcontents
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Doxygen provides a large number of \ref commands "special commands",
|
|
Packit Service |
50c9f2 |
\ref xmlcmds "XML commands", and \ref htmlcmds "HTML commands".
|
|
Packit Service |
50c9f2 |
that can be used to enhance or structure the documentation inside a comment block.
|
|
Packit Service |
50c9f2 |
If you for some reason have a need to define new commands you can do
|
|
Packit Service |
50c9f2 |
so by means of an \e alias definition.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
The definition of an alias should be specified in the configuration file using
|
|
Packit Service |
50c9f2 |
the \ref cfg_aliases "ALIASES" configuration tag.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section custcmd_simple Simple aliases
|
|
Packit Service |
50c9f2 |
The simplest form of an alias is a simple substitution of the form
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
name=value
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
For example defining the following alias:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
ALIASES += sideeffect="\par Side Effects:\n"
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
will allow you to
|
|
Packit Service |
50c9f2 |
put the command `\sideeffect` (or `@sideeffect`) in the documentation, which
|
|
Packit Service |
50c9f2 |
will result in a user-defined paragraph with heading Side Effects:.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that you can put `\n`'s in the value part of an alias to insert newlines
|
|
Packit Service |
50c9f2 |
(in the resulting output). You can put `^^` in the value part of an alias to
|
|
Packit Service |
50c9f2 |
insert a newline as if a physical newline was in the original file.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Also note that you can redefine existing special commands if you wish.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Some commands, such as \ref cmdxrefitem "\\xrefitem" are designed to be used in
|
|
Packit Service |
50c9f2 |
combination with aliases.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section custcmd_complex Aliases with arguments
|
|
Packit Service |
50c9f2 |
Aliases can also have one or more arguments. In the alias definition you then need
|
|
Packit Service |
50c9f2 |
to specify the number of arguments between curly braces. In the value part of the
|
|
Packit Service |
50c9f2 |
definition you can place `\x` markers, where '`x`' represents the argument number starting
|
|
Packit Service |
50c9f2 |
with 1.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Here is an example of an alias definition with a single argument:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
ALIASES += l{1}="\ref \1"
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Inside a comment block you can use it as follows
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/** See \l{SomeClass} for more information. */
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
which would be the same as writing
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/** See \ref SomeClass for more information. */
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that you can overload an alias by a version with multiple arguments, for instance:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
ALIASES += l{1}="\ref \1"
|
|
Packit Service |
50c9f2 |
ALIASES += l{2}="\ref \1 \"\2\""
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
Note that the quotes inside the alias definition have to be escaped with a backslash.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
With these alias definitions, we can write
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/** See \l{SomeClass,Some Text} for more information. */
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
inside the comment block and it will expand to
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/** See \ref SomeClass "Some Text" for more information. */
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
where the command with a single argument would still work as shown before.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Aliases can also be expressed in terms of other aliases, e.g. a new command
|
|
Packit Service |
50c9f2 |
`\reminder` can be expressed as a \ref cmdxrefitem "\\xrefitem" via an intermediate `\xreflist` command
|
|
Packit Service |
50c9f2 |
as follows:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" "
|
|
Packit Service |
50c9f2 |
ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}"
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Note that if for aliases with more than one argument a comma is used as a separator,
|
|
Packit Service |
50c9f2 |
if you want to put a comma inside the command, you will need to escape it with a backslash,
|
|
Packit Service |
50c9f2 |
i.e.
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
\l{SomeClass,Some text\, with an escaped comma}
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
given the alias definition of `\l` in the example above.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\section custcmd_nesting Nesting custom command
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
You can use commands as arguments of aliases, including commands
|
|
Packit Service |
50c9f2 |
defined using aliases.
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
As an example consider the following alias definitions
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
ALIASES += Bold{1}="\1"
|
|
Packit Service |
50c9f2 |
ALIASES += Emph{1}="\1"
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Inside a comment block you can now use:
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
which will expand to
|
|
Packit Service |
50c9f2 |
\verbatim
|
|
Packit Service |
50c9f2 |
/** This is a bold and Emphasized text fragment. */
|
|
Packit Service |
50c9f2 |
\endverbatim
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
\htmlonly
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
Go to the next section or return to the
|
|
Packit Service |
50c9f2 |
index.
|
|
Packit Service |
50c9f2 |
\endhtmlonly
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
|
|
Packit Service |
50c9f2 |
*/
|