docs/tech/tn0003.txt

   1                      Adding wxWidgets class documentation
   2                      ====================================
   3
   4 This note is aimed at people wishing to add documentation for a
   5 class to either the main wxWidgets manual, or to their own
   6 manual.
   7
   8 wxWidgets uses Doxygen to process header input files with embedded
   9 documentation in the form of C++ comments and output in HTML, and XML
  10 (Doxygen itself can also output Latex, manpages, RTF, PDF etc).
  11 See http://www.doxygen.org for more info about Doxygen.
  12
  13 If you want to add documentation of a new class/function to the
  14 existing manual in docs/doxygen, you need to create a new .h file,
  15 e.g. myclass.h, under the interface folder, which contains the public
  16 interface of the new class/function in C++ syntax.
  17 The documentation can then be added in form of Doxygen comments to
  18 the header file.
  19
  20 You may also want to write a separate topic file,
  21 e.g. docs/doxygen/overviews/myclass.h, and add the entry to
  22 docs/doxygen/mainpages/topics.h.
  23
  24 If applicable, also add an entry to one of the docs/doxygen/mainpages/cat_*.h
  25 files.
  26
  27 You can generate a first raw version of myclass.h simply taking its
  28 "real" header and removing all the private and protected sections and
  29 in general removing everything the user "shouldn't know": i.e. all things
  30 which are implementation details.
  31
  32
  33 Running Doxygen
  34 ===============
  35
  36 First, make sure you have a recent version of Doxygen installed in your system
  37 (you'll need Doxygen >= 1.5.4).
  38
  39 On Unix:
  40
  41   1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate]
  42
  43 On Windows:
  44   1) cd wxWidgets/docs/doxygen
  45   2) run regen.bat [format-to-generate]
  46
  47 If you don't specify which format to [re]generate, all output formats will
  48 be enabled. Possible values for [format-to-generate] are: "html", "chm", "latex",
  49 "xml" and "all".
  50
  51 The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder.
  52
  53
  54 Important Dos and Don'ts
  55 ========================
  56
  57 DO:
  58
  59 - Doxygen supports both commands in the form \command and @command;
  60   all wxWidgets documentation uses the @command form.
  61   Follow strictly this rule.
  62
  63 - strive to use dedicated Doxygen commands for e.g. notes, lists,
  64   sections, etc. The "Special commands" page:
  65     http://www.stack.nl/~dimitri/doxygen/commands.html
  66   is your friend!
  67   It's also very important to make a consistent use of the ALIASES
  68   defined by wxWidgets' Doxyfile. Open that file for more info.
  69
  70 - when you write true, false and NULL with their C++ semantic meaning,
  71   then use the @true, @false and @NULL commands.
  72
  73 - separate different paragraphs with an empty comment line.
  74   This is important otherwise Doxygen puts everything in the same
  75   paragraph making the result less readable.
  76
  77 - leave a blank comment line between a @section, @subsection, @page
  78   and the next paragraph.
  79
  80 - test your changes, both reading the generated HTML docs and by looking
  81   at the "doxygen.log" file produced (which will warn you about any
  82   eventual mistake found in the comments).
  83
  84 - quote all the following characters prefixing them with a "@" char:
  85
  86          @  $  \  &  <  >  #  %
  87
  88   unless they appear inside a @code or @verbatim section
  89   (you can also use HTML-style escaping, e.g. &amp; rather than @ escaping)
  90
  91 - when using a Doxygen alias like @itemdef{}, you need to escape the
  92   comma characters which appear on the first argument, otherwise Doxygen
  93   will interpret them as the marker of the end of the first argument and
  94   the beginning of the second argument's text.
  95
  96   E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to
  97        write:
  98             @itemdef{wxEVT_MACRO(id\, func), This is the description of the macro}
  99
 100   Also note that you need to escape only the commas of the first argument's
 101   text; second argument can have up to 10 commas unescaped (see the Doxyfile
 102   for the trick used to implement this).
 103
 104 - for linking use one of:
 105      => the @ref command to refer to topic overviews;
 106      => the () suffix to refer to function members of the same class you're
 107         documenting or to refer to global functions or macros;
 108      => the classname:: operator to refer to functions of classes different
 109         from the one you're documenting;
 110      => the :: prefix to refer to global variables (e.g. ::wxEmptyString).
 111   Class names are auto-linked by Doxygen without the need of any explicit
 112   command.
 113
 114 DON'T:
 115
 116 - use jargon, such as 'gonna', or omit the definite article.
 117   The manual is intended to be a fluent, English document and
 118   not a collection of rough notes.
 119
 120 - use non-alphanumeric characters in link anchors.
 121
 122 - use Doxygen @b @c @e commands when referring to more than a single word;
 123   in that case you need to use the <b>...</b>, <tt>...</tt>, <em>...</em>
 124   HTML-style tags instead
 125
 126 - use HTML style tags for creation of tables or lists.
 127   Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and
 128   @beginDefList, @itemdef, @endDefList, etc.
 129   See the Doxyfile.inc for more info.
 130
 131
 132 Documentation comment for a class
 133 =================================
 134
 135 Start off with:
 136
 137 /**
 138     @class wxMyClass
 139     @wxheader{myclass.h}
 140
 141     ...here goes the description...
 142
 143     @beginEventTable
 144     @event{EVT_SOME_EVENT(id, func)}:
 145             Description for EVT_SOME_EVENT.
 146     @endEventTable
 147
 148     @beginStyleTable
 149     @style{wxSOME_STYLE}:
 150             Description for wxSOME_STYLE.
 151     ...
 152     @endStyleTable
 153
 154     @beginExtraStyleTable
 155     @style{wxSOME_EXTRA_STYLE}:
 156             Description for wxSOME_EXTRA_STYLE.
 157     ...
 158     @endExtraStyleTable
 159
 160     @library{wxbase}
 161     @category{cat_shortcut}
 162
 163     @nativeimpl{wxgtk, wxmsw, ...}
 164     @onlyfor{wxgtk, wxmsw, ...}
 165
 166     @appearance{button.png}
 167
 168     @stdobjects
 169     ...here goes the list of predefined instances...
 170
 171     @see ...here goes the see-also list...
 172          you can make references to topic overviews or other
 173          manual pages using the @ref command
 174 */
 175
 176 Note that everything *except* the @class, @wxheader, @library and @category
 177 commands are optionals.
 178
 179
 180
 181 Documentation comment for a function
 182 ====================================
 183
 184 Start off with:
 185
 186 /**
 187     ...here goes the description of the function....
 188
 189     @param param1
 190         ...here goes the description for the first parameter of this function
 191     @param param2
 192         ...here goes the description for the second parameter of this function
 193         ...
 194
 195     @return
 196     ...here goes the description of what the function returns...
 197
 198     @note ...here go any eventual notes about this function...
 199
 200     @remarks ...here go any eventual remarks about this function...
 201
 202     @see ...here goes the see-also list...
 203  */
 204
 205 Note that the @return, @note, @remarks, @see commands are optional.
 206
 207 The @param command has an optional attribute specifying the direction of
 208 the attribute. Possible values are "in" and "out". E.g.
 209
 210 /**
 211  * Copies bytes from a source memory area to a destination memory area,
 212  * where both areas may not overlap.
 213  * @param[out]     dest   The memory area to copy to.
 214  * @param[in]      src    The memory area to copy from.
 215  * @param[in]      n      The number of bytes to copy.
 216  * @param[in,out]  pmisc  Used both as input and as output.
 217  */
 218 void func(void *dest, const void *src, size_t n, void *pmisc);
 219
 220
 221 Documentation comment for a topic overview
 222 ==========================================
 223
 224 Topic overviews are stored inside the docs/doxygen/overviews folder
 225 and are completely placed inside a single comment block in the form of:
 226
 227 /*!
 228
 229  @page overview_tname wxSomeStuff overview
 230
 231  This page provides an overview of the wxSomeStuff and related classes.
 232  ....
 233
 234  @li @ref overview_tname_intro
 235  @li @ref overview_tname_details
 236  ...
 237
 238  <hr>
 239
 240
 241  @section overview_tname_intro Introduction
 242
 243  ...here goes the introduction to this topic...
 244
 245
 246  @section overview_tname_details Details
 247
 248  ...here go the details to this topic...
 249
 250 */
 251
 252 Note that there is a convention in the anchor link names.
 253 Doxygen in fact requires that for each @page, @section, @subsection, etc tag,
 254 there is a corresponding link anchor.
 255
 256 The following conventions are used in wxWidgets doxygen comments:
 257
 258 1) all "main" pages of the manual (those which are placed in
 259    docs/doxygen/mainpages) have link anchors which begin with "page_"
 260
 261 2) all topic overviews (those which are placed in docs/doxygen/overviews) have
 262    link anchors which begin with "overview_"
 263
 264 3) all @section, @subsection, @subsubsection tags should have as link anchor
 265    name the name of the parent section plus a specific word separated with an
 266    underscore; e.g.:
 267
 268 /*!
 269
 270  @page overview_tname wxSomeStuff overview
 271
 272  @section overview_tname_intro Introduction
 273   @subsection overview_tname_intro_firstpart First part
 274   @subsection overview_tname_intro_secondpart Second part
 275    @subsubsection overview_tname_intro_secondpart_sub Second part subsection
 276   @subsection overview_tname_intro_thirdpart Third part
 277
 278  @section overview_tname_details Details
 279  ...
 280
 281 */
 282
 283
 284 === EOF ===
 285
 286 Author: FM (along the lines of the previous technote about tex2rtf)
 287 Version: $Id$