doc/custcmd.doc

   1 /******************************************************************************
   2  *
   3  *
   4  *
   5  * Copyright (C) 1997-2015 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 \tableofcontents{html,latex}
  20
  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.
  26
  27 The definition of an alias should be specified in the configuration file using
  28 the \ref cfg_aliases "ALIASES" configuration tag.
  29
  30 \section custcmd_simple Simple aliases
  31 The simplest form of an alias is a simple substitution of the form
  32 \verbatim
  33  name=value
  34 \endverbatim
  35  For example defining the following alias:
  36 \verbatim
  37  ALIASES += sideeffect="\par Side Effects:\n"
  38 \endverbatim
  39  will allow you to
  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>.
  42
  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.
  46
  47 Note when you need a literal `{` or `}` or `,` in the value part of an alias you have to
  48 escape them by means of a backslash (`\`), this can lead to conflicts with the
  49 commands \c \\{ and \c \\} for these it is advised to use the version \c @@{ and \c @@} or
  50 use a double escape (\c \\\\{ and \c \\\\})
  51
  52 Also note that you can redefine existing special commands if you wish.
  53
  54 Some commands, such as \ref cmdxrefitem "\\xrefitem" are designed to be used in
  55 combination with aliases.
  56
  57 \section custcmd_complex Aliases with arguments
  58 Aliases can also have one or more arguments. In the alias definition you then need
  59 to specify the number of arguments between curly braces. In the value part of the
  60 definition you can place `\x` markers, where '`x`' represents the argument number starting
  61 with 1.
  62
  63 Here is an example of an alias definition with a single argument:
  64 \verbatim
  65 ALIASES += l{1}="\ref \1"
  66 \endverbatim
  67
  68 Inside a comment block you can use it as follows
  69 \verbatim
  70 /** See \l{SomeClass} for more information. */
  71 \endverbatim
  72 which would be the same as writing
  73 \verbatim
  74 /** See \ref SomeClass for more information. */
  75 \endverbatim
  76
  77 Note that you can overload an alias by a version with multiple arguments, for instance:
  78 \verbatim
  79 ALIASES += l{1}="\ref \1"
  80 ALIASES += l{2}="\ref \1 \"\2\""
  81 \endverbatim
  82 Note that the quotes inside the alias definition have to be escaped with a backslash.
  83
  84 With these alias definitions, we can write
  85 \verbatim
  86 /** See \l{SomeClass,Some Text} for more information. */
  87 \endverbatim
  88 inside the comment block and it will expand to
  89 \verbatim
  90 /** See \ref SomeClass "Some Text" for more information. */
  91 \endverbatim
  92 where the command with a single argument would still work as shown before.
  93
  94 Aliases can also be expressed in terms of other aliases, e.g. a new command
  95 `\reminder` can be expressed as a \ref cmdxrefitem "\\xrefitem" via an intermediate `\xreflist` command
  96 as follows:
  97 \verbatim
  98 ALIASES += xreflist{3}="\xrefitem \1 \"\2\" \"\3\" "
  99 ALIASES += reminder="\xreflist{reminders,Reminder,Reminders}"
 100 \endverbatim
 101
 102 Note that if for aliases with more than one argument a comma is used as a separator,
 103 if you want to put a comma inside the command, you will need to escape it with a backslash,
 104 i.e.
 105 \verbatim
 106 \l{SomeClass,Some text\, with an escaped comma}
 107 \endverbatim
 108 given the alias definition of `\l` in the example above.
 109
 110 \section custcmd_nesting Nesting custom command
 111
 112 You can use commands as arguments of aliases, including commands
 113 defined using aliases.
 114
 115 As an example consider the following alias definitions
 116
 117 \verbatim
 118 ALIASES += Bold{1}="<b>\1</b>"
 119 ALIASES += Emph{1}="<em>\1</em>"
 120 \endverbatim
 121
 122 Inside a comment block you can now use:
 123 \verbatim
 124 /** This is a \Bold{bold \Emph{and} Emphasized} text fragment. */
 125 \endverbatim
 126 which will expand to
 127 \verbatim
 128 /** This is a <b>bold <em>and</em> Emphasized</b> text fragment. */
 129 \endverbatim
 130
 131
 132 \htmlonly
 133 <br/>
 134 Go to the <a href="external.html">next</a> section or return to the
 135  <a href="index.html">index</a>.
 136 \endhtmlonly
 137
 138
 139 */