1 /******************************************************************************
5 * Copyright (C) 1997-2015 by Dimitri van Heesch.
7 * Permission to use, copy, modify, and distribute this software and its
8 * documentation under the terms of the GNU General Public License is hereby
9 * granted. No representations are made about the suitability of this software
10 * for any purpose. It is provided "as is" without express or implied warranty.
11 * See the GNU General Public License for more details.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
17 /*! \page custcmd Custom Commands
21 Doxygen provides a large number of \ref commands "special commands",
22 \ref xmlcmds "XML commands", and \ref htmlcmds "HTML commands".
23 that can be used to enhance or structure the documentation inside a comment block.
24 If you for some reason have a need to define new commands you can do
25 so by means of an \e alias definition.
27 The definition of an alias should be specified in the configuration file using
28 the \ref cfg_aliases "ALIASES" configuration tag.
30 \section custcmd_simple Simple aliases
31 The simplest form of an alias is a simple substitution of the form
35 For example defining the following alias:
37 ALIASES += sideeffect="\par Side Effects:\n"
40 put the command `\sideeffect` (or `@sideeffect`) in the documentation, which
41 will result in a user-defined paragraph with heading <b>Side Effects:</b>.
43 Note that you can put `\n`'s in the value part of an alias to insert newlines
44 (in the resulting output). You can put `^^` in the value part of an alias to
45 insert a newline as if a physical newline was in the original file.
47 Also note that you can redefine existing special commands if you wish.
49 Some commands, such as \ref cmdxrefitem "\\xrefitem" are designed to be used in
50 combination with aliases.
52 \section custcmd_complex Aliases with arguments
53 Aliases can also have one or more arguments. In the alias definition you then need
54 to specify the number of arguments between curly braces. In the value part of the
55 definition you can place `\x` markers, where '`x`' represents the argument number starting
58 Here is an example of an alias definition with a single argument:
60 ALIASES += l{1}="\ref \1"
63 Inside a comment block you can use it as follows
65 /** See \l{SomeClass} for more information. */
67 which would be the same as writing
69 /** See \ref SomeClass for more information. */
72 Note that you can overload an alias by a version with multiple arguments, for instance:
74 ALIASES += l{1}="\ref \1"
75 ALIASES += l{2}="\ref \1 \"\2\""
77 Note that the quotes inside the alias definition have to be escaped with a backslash.
79 With these alias definitions, we can write
81 /** See \l{SomeClass,Some Text} for more information. */
83 inside the comment block and it will expand to
85 /** See \ref SomeClass "Some Text" for more information. */
87 where the command with a single argument would still work as shown before.
89 Aliases can also be expressed in terms of other aliases, e.g. a new command
90 `\reminder` can be expressed as a \ref cmdxrefitem "\\xrefitem" via an intermediate `\xreflist` command
93 ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" "
94 ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}"
97 Note that if for aliases with more than one argument a comma is used as a separator,
98 if you want to put a comma inside the command, you will need to escape it with a backslash,
101 \l{SomeClass,Some text\, with an escaped comma}
103 given the alias definition of `\l` in the example above.
105 \section custcmd_nesting Nesting custom command
107 You can use commands as arguments of aliases, including commands
108 defined using aliases.
110 As an example consider the following alias definitions
113 ALIASES += Bold{1}="<b>\1</b>"
114 ALIASES += Emph{1}="<em>\1</em>"
117 Inside a comment block you can now use:
119 /** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */
123 /** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */
129 Go to the <a href="external.html">next</a> section or return to the
130 <a href="index.html">index</a>.