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. To futher speed-up HTML help books loading
  52 in your application, you may use hhp2cached (utils/hhp2cached).
  53
  54 src/msw/makefile.vc contains targets for generating various
  55 formats of documentation. You may like to do something similar if
  56 writing your own manual.
  57
  58 Important Dos and Don'ts
  59 ========================
  60
  61 DO:
  62
  63 - put a space (or \rtfsp) at the end of a line or start of a line where
  64   a command ends or starts the line. Otherwise, spaces will be
  65   omitted in Word or WinHelp RTF. For example:
  66
  67   See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp
  68   for a list of possible values.
  69
  70 - leave a blank line at the end of the class file. This is
  71   important, or the Word RTF table of contents will be messed up.
  72
  73 - leave a blank line between a heading and the next paragraph.
  74
  75 - test your changes, preferably converting the manual to WinHelp
  76   format and running through the Windows help compiler to check
  77   for missing labels, etc.
  78
  79 DON'T:
  80
  81 - use jargon, such as 'gonna', or omit the definite article.
  82   The manual is intended to be a fluent, English document and
  83   not a collection of rough notes.
  84
  85 - use non-alphanumeric characters in labels.
  86
  87 - use incompatible Latex syntax, such as {\it \bf word} (use a pair
  88   of braces for each formatting command).
  89
  90 - leave multiple consecutive blank lines, or blank lines between
  91   \items in a list.
  92
  93 Troubleshooting
  94 ===============
  95
  96 Please see the troubleshooting section in the Tex2RTF manual, but
  97 here is one important tip:
  98
  99   If you get a "Macro not found: \end{document}" error,
 100    this is a spurious side-effect of an earlier error, usually an
 101    incorrect number of arguments to a command. The location of the
 102    true error is then anywhere in the document.
 103
 104    To home in on the error, try putting \begin{comment}...\end{comment}
 105    around much of the document, and then move the \begin{comment}
 106    line down until the error manifests itself again. Note that
 107    you can abort Tex2RTF after the syntax error stage by clicking
 108    on the close button, so you don't have to wait while the whole
 109    document is processed.
 110
 111    Before looking at a file in detail, you can comment out the
 112    \input{myclass.tex} line in classes.tex using the single
 113    line comment character (%) to see whether it was that file that
 114    caused the problem.
 115
 116 Elements in a class file
 117 ========================
 118
 119 Start off with:
 120
 121 \section{\class{wxMyClass}}\label{wxmyclass}
 122
 123 (note that labels can only go on sections such as \chapter,
 124 \section, \subsection, \membersection, but not on \wxheading, for
 125 example.)
 126
 127 Describe the class briefly.
 128
 129 Then there are several \wxheading sections:
 130
 131 \wxheading{Derived from}
 132
 133 List the base classes, with line breaks following each one (\\)
 134 except the last.
 135
 136 \wxheading{Include files}
 137
 138 List the relevant include files, for example:
 139
 140 <wx/myclass.h>
 141
 142 \wxheading{Predefined objects}
 143
 144 List any predefined objects, such as:
 145
 146 {\bf wxNullMyClass}
 147
 148 \wxheading{See also}
 149
 150 List any relevant classes or topics, using \helpref.
 151
 152 \latexignore{\rtfignore{\wxheading{Members}}}
 153
 154 This generates the required heading for the member definitions.
 155 Put the constructors first, then in alphabetical order, the other
 156 members.
 157
 158 Here's an example of documentation for a member function:
 159
 160          --------------------:x-----------------------
 161
 162 \membersection{wxBitmap::Create}\label{wxbitmapcreate}
 163
 164 \func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height},
 165  \param{int}{ depth = -1}}
 166
 167 Creates a fresh bitmap. If the final argument is omitted, the display depth of
 168 the screen is used.
 169
 170 \func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type},
 171  \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
 172
 173 Creates a bitmap from the given data, which can be of arbitrary type.
 174
 175 \wxheading{Parameters}
 176
 177 \docparam{width}{The width of the bitmap in pixels.}
 178
 179 \docparam{height}{The height of the bitmap in pixels.}
 180
 181 \docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.}
 182
 183 \docparam{data}{Data whose type depends on the value of {\it type}.}
 184
 185 \docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list
 186 of possible values.}
 187
 188 \wxheading{Return value}
 189
 190 TRUE if the call succeeded, FALSE otherwise.
 191
 192 \wxheading{Remarks}
 193
 194 The first form works on all platforms. The portability of the second form depends on the
 195 type of data.
 196
 197 \wxheading{See also}
 198
 199 \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}
 200
 201          --------------------:x-----------------------
 202
 203 Note the use of \docparam to document parameters; and the fact
 204 that several overloaded forms of the same member function are
 205 documented within the same \membersection.
 206