|
1 /****************************************************************************** |
|
2 * |
|
3 * |
|
4 * |
|
5 * Copyright (C) 1997-2008 by Dimitri van Heesch. |
|
6 * |
|
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. |
|
12 * |
|
13 * Documents produced by Doxygen are derivative works derived from the |
|
14 * input used in their production; they are not affected by this license. |
|
15 * |
|
16 */ |
|
17 /*! \page custcmd Custom Commands |
|
18 |
|
19 Doxygen provides a large number of \ref commands "special commands", |
|
20 \ref xmlcmds "XML commands", and \ref htmlcmds "HTML commands". |
|
21 that can be used to enhance or structure the documentation inside a comment block. |
|
22 If you for some reason have a need to define new commands you can do |
|
23 so by means of an \e alias definition. |
|
24 |
|
25 The definition of an alias should be specified in the configuration file using |
|
26 the \ref cfg_aliases "ALIASES" configuration tag. |
|
27 |
|
28 \section custcmd_simple Simple aliases |
|
29 The simplest form of an alias is a simple substitution of the form |
|
30 \verbatim |
|
31 name=value |
|
32 \endverbatim |
|
33 For example defining the following alias: |
|
34 \verbatim |
|
35 ALIASES += sideeffect="\par Side Effects:\n" |
|
36 \endverbatim |
|
37 will allow you to |
|
38 put the command \\sideeffect (or \@sideeffect) in the documentation, which |
|
39 will result in a user-defined paragraph with heading <b>Side Effects:</b>. |
|
40 |
|
41 Note that you can put \\n's in the value part of an alias to insert newlines. |
|
42 |
|
43 Also note that you can redefine existing special commands if you wish. |
|
44 |
|
45 Some commands, such as \ref cmdxrefitem "\\xrefitem" are designed to be used in |
|
46 combination with aliases. |
|
47 |
|
48 \section custcmd_complex Aliases with arguments |
|
49 Aliases can also have one or more arguments. In the alias definition you then need |
|
50 to specify the number of arguments between curly braces. In the value part of the |
|
51 definition you can place \\x markers, where 'x' represents the argument number starting |
|
52 with 1. |
|
53 |
|
54 Here is an example of an alias definition with a single argument: |
|
55 \verbatim |
|
56 ALIASES += l{1}="\ref \1" |
|
57 \endverbatim |
|
58 |
|
59 Inside a comment block you can use it as follows |
|
60 \verbatim |
|
61 /** See \l{SomeClass} for more information. */ |
|
62 \endverbatim |
|
63 which would be the same as writing |
|
64 \verbatim |
|
65 /** See \ref SomeClass for more information. */ |
|
66 \endverbatim |
|
67 |
|
68 Note that you can overload an alias by a version with multiple arguments, for instance: |
|
69 \verbatim |
|
70 ALIASES += l{1}="\ref \1" |
|
71 ALIASES += l{2}="\ref \1 \"\2\"" |
|
72 \endverbatim |
|
73 Note that the quotes inside the alias definition have to be escaped with a backslash. |
|
74 |
|
75 With these alias definitions, we can write |
|
76 \verbatim |
|
77 /** See \l{SomeClass,Some Text} for more information. */ |
|
78 \endverbatim |
|
79 inside the comment block and it will expand to |
|
80 \verbatim |
|
81 /** See \ref SomeClass "Some Text" for more information. */ |
|
82 \endverbatim |
|
83 where the command with a single argument would still work as shown before. |
|
84 |
|
85 Aliases can also be expressed in terms of other aliases, e.g. a new command |
|
86 \\reminder can be expressed as a \\xrefitem via an intermediate \\xreflist command |
|
87 as follows: |
|
88 \verbatim |
|
89 ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" " \ |
|
90 ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}" \ |
|
91 \endverbatim |
|
92 |
|
93 Note that if for aliases with more than one argument a comma is used as a separator, |
|
94 if you want to put a comma inside the command, you will need to escape it with a backslash, |
|
95 i.e. |
|
96 \verbatim |
|
97 \l{SomeClass,Some text\, with an escaped comma} |
|
98 \endverbatim |
|
99 given the alias definition of \\l in the example above. |
|
100 |
|
101 \section custcmd_nesting Nesting custom command |
|
102 |
|
103 You can use commands as arguments of aliases, including commands |
|
104 defined using aliases. |
|
105 |
|
106 As an example consider the following alias definitions |
|
107 |
|
108 \verbatim |
|
109 ALIASES += Bold{1}="<b>\1</b>" |
|
110 ALIASES += Emph{1}="<em>\1</em>" |
|
111 \endverbatim |
|
112 |
|
113 Inside a comment block you can now use: |
|
114 \verbatim |
|
115 /** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */ |
|
116 \endverbatim |
|
117 which will expand to |
|
118 \verbatim |
|
119 /** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */ |
|
120 \endverbatim |
|
121 |
|
122 |
|
123 */ |