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 - for linking use one of:
  97      => the @ref command to refer to topic overviews;
  98      => the () suffix to refer to function members of the same class you're
  99         documenting or to refer to global functions or macros;
 100      => the classname:: operator to refer to functions of classes different
 101         from the one you're documenting;
 102      => the :: prefix to refer to global variables (e.g. ::wxEmptyString).
 103   Class names are auto-linked by Doxygen without the need of any explicit command.
 104
 105 DON'T:
 106
 107 - use jargon, such as 'gonna', or omit the definite article.
 108   The manual is intended to be a fluent, English document and
 109   not a collection of rough notes.
 110
 111 - use non-alphanumeric characters in link anchors.
 112
 113 - use Doxygen @b @c @e commands when referring to more than a single word;
 114   in that case you need to use the <b>...</b>, <tt>...</tt>, <em>...</em>
 115   HTML-style tags instead
 116
 117 - use HTML style tags for creation of tables or lists.
 118   Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and
 119   @beginDefList, @itemdef, @endDefList, etc.
 120   See the Doxyfile.inc for more info.
 121
 122
 123 Documentation comment for a class
 124 =================================
 125
 126 Start off with:
 127
 128 /**
 129     @class wxMyClass
 130     @wxheader{myclass.h}
 131
 132     ...here goes the description...
 133
 134     @beginEventTable
 135     @event{EVT_SOME_EVENT(id, func)}:
 136             Description for EVT_SOME_EVENT.
 137     @endEventTable
 138
 139     @beginStyleTable
 140     @style{wxSOME_STYLE}:
 141             Description for wxSOME_STYLE.
 142     ...
 143     @endStyleTable
 144
 145     @beginExtraStyleTable
 146     @style{wxSOME_EXTRA_STYLE}:
 147             Description for wxSOME_EXTRA_STYLE.
 148     ...
 149     @endExtraStyleTable
 150
 151     @library{wxbase}
 152     @category{cat_shortcut}
 153
 154     @nativeimpl{wxgtk, wxmsw, ...}
 155     @onlyfor{wxgtk, wxmsw, ...}
 156
 157     @appearance{button.png}
 158
 159     @stdobjects
 160     ...here goes the list of predefined instances...
 161
 162     @see ...here goes the see-also list...
 163          you can make references to topic overviews or other
 164          manual pages using the @ref command
 165 */
 166
 167 Note that everything *except* the @class, @wxheader, @library and @category
 168 commands are optionals.
 169
 170
 171
 172 Documentation comment for a function
 173 ====================================
 174
 175 Start off with:
 176
 177 /**
 178     ...here goes the description of the function....
 179
 180     @param param1
 181         ...here goes the description for the first parameter of this function
 182     @param param2
 183         ...here goes the description for the second parameter of this function
 184         ...
 185
 186     @return
 187     ...here goes the description of what the function returns...
 188
 189     @note ...here go any eventual notes about this function...
 190
 191     @remarks ...here go any eventual remarks about this function...
 192
 193     @see ...here goes the see-also list...
 194  */
 195
 196 Note that the @return, @note, @remarks, @see commands are optional.
 197
 198 The @param command has an optional attribute specifying the direction of
 199 the attribute. Possible values are "in" and "out". E.g.
 200
 201 /**
 202  * Copies bytes from a source memory area to a destination memory area,
 203  * where both areas may not overlap.
 204  * @param[out]     dest   The memory area to copy to.
 205  * @param[in]      src    The memory area to copy from.
 206  * @param[in]      n      The number of bytes to copy.
 207  * @param[in,out]  pmisc  Used both as input and as output.
 208  */
 209 void func(void *dest, const void *src, size_t n, void *pmisc);
 210
 211
 212 Documentation comment for a topic overview
 213 ==========================================
 214
 215 Topic overviews are stored inside the docs/doxygen/overviews folder
 216 and are completely placed inside a single comment block in the form of:
 217
 218 /*!
 219
 220  @page overview_tname wxSomeStuff overview
 221
 222  This page provides an overview of the wxSomeStuff and related classes.
 223  ....
 224
 225  @li @ref overview_tname_intro
 226  @li @ref overview_tname_details
 227  ...
 228
 229  <hr>
 230
 231
 232  @section overview_tname_intro Introduction
 233
 234  ...here goes the introduction to this topic...
 235
 236
 237  @section overview_tname_details Details
 238
 239  ...here go the details to this topic...
 240
 241 */
 242
 243 Note that there is a convention in the anchor link names.
 244 Doxygen in fact requires that for each @page, @section, @subsection, etc tag,
 245 there is a corresponding link anchor.
 246
 247 The following conventions are used in wxWidgets doxygen comments:
 248
 249 1) all "main" pages of the manual (those which are placed in docs/doxygen/mainpages)
 250    have link anchors which begin with "page_"
 251
 252 2) all topic overviews (those which are placed in docs/doxygen/overviews) have link
 253    anchors which begin with "overview_"
 254
 255 3) all @section, @subsection, @subsubsection tags should have as link anchor name
 256    the name of the parent section plus a specific word separed with an underscore; e.g.:
 257
 258 /*!
 259
 260  @page overview_tname wxSomeStuff overview
 261
 262  @section overview_tname_intro Introduction
 263   @subsection overview_tname_intro_firstpart First part
 264   @subsection overview_tname_intro_secondpart Second part
 265    @subsubsection overview_tname_intro_secondpart_sub Second part subsection
 266   @subsection overview_tname_intro_thirdpart Third part
 267
 268  @section overview_tname_details Details
 269  ...
 270
 271 */
 272
 273
 274 === EOF ===
 275
 276 Author: FM (under the lines of the previous technote about tex2rtf)
 277 Version: $Id$