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