docs/tech/tn0003.txt

   1                      Adding wxWindows class documentation
   2                      ====================================
   3
   4 This note is aimed at people wishing to add documentation for a
   5 class to either the main wxWindows manual, or to their own
   6 manual.
   7
   8 wxWindows uses Tex2RTF to process Latex-like input files (.tex)
   9 and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided
  10 in the wxWindows distribution and in the CVS archive, under
  11 utils/tex2rtf. Please start by perusing the Tex2RTF manual.
  12
  13 If adding to the existing manual in docs/latex/wx, you need to
  14 create a new .tex file, e.g. myclass.tex, and add it to the
  15 list of classes in classes.tex (in strict alphabetical order).
  16 You may also want to write a separate topic file, e.g. tmyclass.tex,
  17 and add the entry to topics.tex.
  18
  19 If compiling a separate manual, copy an existing set of files from the
  20 wxWindows manual or a contribution. Contribution documentation
  21 normally goes in the contrib/docs hierarchy, with the source
  22 going in a latex/mycontrib subdirectory.
  23
  24 You can generate a first pass at the myclass.tex file by
  25 compiling and running HelpGen (utils/helpgen).
  26
  27 Running Tex2RTF
  28 ===============
  29
  30 See the Tex2RTF documentation, but here are some forms:
  31
  32 For HTML:
  33
  34   tex2rtf manual.tex manual.htm -html -twice
  35
  36 Use of -twice allows Tex2RTF to resolve references. Note that
  37 if both filenames are given (first two parameters on the command
  38 line) then Tex2RTF will run in non-interactive mode.
  39
  40 For WinHelp RTF:
  41
  42   tex2rtf manual.tex manual.rtf -winhelp -twice
  43
  44 For Word RTF:
  45
  46   tex2rtf manual.tex manual.rtf -rtf -twice
  47
  48 If you wish to generate documentation for wxHTML Help Viewer
  49 (or Windows HTML Help), set htmlWorkshopFiles to true in your
  50 tex2rtf.ini file. See also the wxHTML Notes section in the
  51 wxWindows manual.
  52
  53 src/msw/makefile.vc contains targets for generating various
  54 formats of documentation. You may like to do something similar if
  55 writing your own manual.
  56
  57 Important Dos and Don'ts
  58 ========================
  59
  60 DO:
  61
  62 - put a space (or \rtfsp) at the end of a line or start of a line where
  63   a command ends or starts the line. Otherwise, spaces will be
  64   omitted in Word or WinHelp RTF. For example:
  65
  66   See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp
  67   for a list of possible values.
  68
  69 - leave a blank line at the end of the class file. This is
  70   important, or the Word RTF table of contents will be messed up.
  71
  72 - leave a blank line between a heading and the next paragraph.
  73
  74 - test your changes, preferably converting the manual to WinHelp
  75   format and running through the Windows help compiler to check
  76   for missing labels, etc.
  77
  78 DON'T:
  79
  80 - use jargon, such as 'gonna', or omit the definite article.
  81   The manual is intended to be a fluent, English document and
  82   not a collection of rough notes.
  83
  84 - use non-alphanumeric characters in labels.
  85
  86 - use incompatible Latex syntax, such as {\it \bf word} (use a pair
  87   of braces for each formatting command).
  88
  89 - leave multiple consecutive blank lines, or blank lines between
  90   \items in a list.
  91
  92 Troubleshooting
  93 ===============
  94
  95 Please see the troubleshooting section in the Tex2RTF manual, but
  96 here is one important tip:
  97
  98   If you get a "Macro not found: \end{document}" error,
  99    this is a spurious side-effect of an earlier error, usually an
 100    incorrect number of arguments to a command. The location of the
 101    true error is then anywhere in the document.
 102
 103    To home in on the error, try putting \begin{comment}...\end{comment}
 104    around much of the document, and then move the \begin{comment}
 105    line down until the error manifests itself again. Note that
 106    you can abort Tex2RTF after the syntax error stage by clicking
 107    on the close button, so you don't have to wait while the whole
 108    document is processed.
 109
 110    Before looking at a file in detail, you can comment out the
 111    \input{myclass.tex} line in classes.tex using the single
 112    line comment character (%) to see whether it was that file that
 113    caused the problem.
 114
 115 Elements in a class file
 116 ========================
 117
 118 Start off with:
 119
 120 \section{\class{wxMyClass}}\label{wxmyclass}
 121
 122 (note that labels can only go on sections such as \chapter,
 123 \section, \subsection, \membersection, but not on \wxheading, for
 124 example.)
 125
 126 Describe the class briefly.
 127
 128 Then there are several \wxheading sections:
 129
 130 \wxheading{Derived from}
 131
 132 List the base classes, with line breaks following each one (\\)
 133 except the last.
 134
 135 \wxheading{Include files}
 136
 137 List the relevant include files, for example:
 138
 139 <wx/myclass.h>
 140
 141 \wxheading{Predefined objects}
 142
 143 List any predefined objects, such as:
 144
 145 {\bf wxNullMyClass}
 146
 147 \wxheading{See also}
 148
 149 List any relevant classes or topics, using \helpref.
 150
 151 \latexignore{\rtfignore{\wxheading{Members}}}
 152
 153 This generates the required heading for the member definitions.
 154 Put the constructors first, then in alphabetical order, the other
 155 members.
 156
 157 Here's an example of documentation for a member function:
 158
 159          --------------------:x-----------------------
 160
 161 \membersection{wxBitmap::Create}\label{wxbitmapcreate}
 162
 163 \func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height},
 164  \param{int}{ depth = -1}}
 165
 166 Creates a fresh bitmap. If the final argument is omitted, the display depth of
 167 the screen is used.
 168
 169 \func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type},
 170  \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
 171
 172 Creates a bitmap from the given data, which can be of arbitrary type.
 173
 174 \wxheading{Parameters}
 175
 176 \docparam{width}{The width of the bitmap in pixels.}
 177
 178 \docparam{height}{The height of the bitmap in pixels.}
 179
 180 \docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.}
 181
 182 \docparam{data}{Data whose type depends on the value of {\it type}.}
 183
 184 \docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list
 185 of possible values.}
 186
 187 \wxheading{Return value}
 188
 189 TRUE if the call succeeded, FALSE otherwise.
 190
 191 \wxheading{Remarks}
 192
 193 The first form works on all platforms. The portability of the second form depends on the
 194 type of data.
 195
 196 \wxheading{See also}
 197
 198 \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}
 199
 200          --------------------:x-----------------------
 201
 202 Note the use of \docparam to document parameters; and the fact
 203 that several overloaded forms of the same member function are
 204 documented within the same \membersection.
 205