ugh. Nesting the (per class) plugin sentries can require them to

[wxWidgets.git] / docs / tech / tn0003.txt

                     Adding wxWindows class documentation
                     ====================================

This note is aimed at people wishing to add documentation for a
class to either the main wxWindows manual, or to their own
manual.

wxWindows uses Tex2RTF to process Latex-like input files (.tex)
and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided
in the wxWindows distribution and in the CVS archive, under
utils/tex2rtf. Please start by perusing the Tex2RTF manual.

If adding to the existing manual in docs/latex/wx, you need to
create a new .tex file, e.g. myclass.tex, and add it to the
list of classes in classes.tex (in strict alphabetical order).
You may also want to write a separate topic file, e.g. tmyclass.tex,
and add the entry to topics.tex.  Also, if applicable, and an entry
to category.tex.

If compiling a separate manual, copy an existing set of files from the
wxWindows manual or a contribution. Contribution documentation
normally goes in the contrib/docs hierarchy, with the source
going in a latex/mycontrib subdirectory.

You can generate a first pass at the myclass.tex file by
compiling and running HelpGen (utils/helpgen).

Running Tex2RTF
===============

See the Tex2RTF documentation, but here are some forms:

For HTML:

  tex2rtf manual.tex manual.htm -html -twice

Use of -twice allows Tex2RTF to resolve references. Note that
if both filenames are given (first two parameters on the command
line) then Tex2RTF will run in non-interactive mode.

For WinHelp RTF:

  tex2rtf manual.tex manual.rtf -winhelp -twice

For Word RTF:

  tex2rtf manual.tex manual.rtf -rtf -twice

If you wish to have a GUI display show the status of what is happening
as the conversion is happening, use the '-interactive' command line
parameter, and then choose FILE|GO from the menu.  For example:

   tex2rtf manual.tex manual.rtf -rtf -twice -interactive

NOTE: You must be using the latest tex2rtf which was released with
v2.2.0 of wxWindows to use the -interactive switch

If you wish to generate documentation for wxHTML Help Viewer
(or Windows HTML Help), set htmlWorkshopFiles to true in your
tex2rtf.ini file. See also the wxHTML Notes section in the
wxWindows manual. To futher speed-up HTML help books loading
in your application, you may use hhp2cached (utils/hhp2cached).

src/msw/makefile.vc contains targets for generating various
formats of documentation. You may like to do something similar if
writing your own manual.

Important Dos and Don'ts
========================

DO:

- put a space (or \rtfsp) at the end of a line or start of a line where
  a command ends or starts the line. Otherwise, spaces will be
  omitted in Word or WinHelp RTF. For example:

  See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp
  for a list of possible values.

- leave a blank line at the end of the class file. This is
  important, or the Word RTF table of contents will be messed up.

- leave a blank line between a heading and the next paragraph.

- test your changes, preferably converting the manual to WinHelp
  format and running through the Windows help compiler to check
  for missing labels, etc.

- quote all '_' characters with a '\' character (e.g. "MY\_PROGRAM" 
  unless the '_' is inside a comment or a \begin{verbatim} ...
  \end{verbatim} block

- check that your changes/additions to any TEX documentation 
  compiles before checking it in!  Use the '-checkcurleybrace' 
  and '-checksyntax' commandline parameters (or the OPTIONS menu 
  if running in GUI mode) to check for some of the more common 
  mistakes.  See TROUBLESHOOTING below for more details


DON'T:

- use jargon, such as 'gonna', or omit the definite article.
  The manual is intended to be a fluent, English document and
  not a collection of rough notes.

- use non-alphanumeric characters in labels.

- use incompatible Latex syntax, such as {\it \bf word} (use a pair
  of braces for each formatting command).

- leave multiple consecutive blank lines, or blank lines between
  \items in a list.

- use \verb$....$ syntax.  Instead use \tt{....} syntax

- add the following tokens anywhere except on a line by themselves:
	\begin{verbatim}
	\begin{toocomplex}
	\end{verbatim}
	\end{toocomplex}
	\verb
	\begin{comment}
	\end{comment}
	\verbatiminput
	\par
	\input
	\helpinput
	\include
	

Troubleshooting
===============

Please see the troubleshooting section in the Tex2RTF manual, but
here is one important tip:

   If you get a "Macro not found: \end{document}" error,
   this is a spurious side-effect of an earlier error, usually an
   incorrect number of arguments to a command. The location of the
   true error is then anywhere in the document.

   To home in on the error, try putting \begin{comment}...\end{comment}
   around much of the document, and then move the \begin{comment}
   line down until the error manifests itself again. Note that
   you can abort Tex2RTF after the syntax error stage by clicking
   on the close button, so you don't have to wait while the whole
   document is processed.

   Before looking at a file in detail, you can comment out the
   \input{myclass.tex} line in classes.tex using the single
   line comment character (%) to see whether it was that file that
   caused the problem.

	When making changes/additions to the documentation, always use 
	the '-checkcurleybraces' and '-checksyntax' commandline parameters
	(or turn these options on in the GUI version via the OPTIONS menu 
	choice), BEFORE checking in your changes.  These two debugging 
	options will catch many of the more common mistakes that are made
	while writing documents, plus they will catch some of the uses 
	of TeX that are correct syntax-wise, but that tex2rtf cannot 
	handle properly, and report the problems (usually along with
	a filename and line number that they occur in!) in the programs
	output window (GUI mode).

Elements in a class file
========================

Start off with:

\section{\class{wxMyClass}}\label{wxmyclass}

(note that labels can only go on sections such as \chapter,
\section, \subsection, \membersection, but not on \wxheading, for
example.)

Describe the class briefly.

Then there are several \wxheading sections:

\wxheading{Derived from}

List the base classes, with line breaks following each one (\\)
except the last.

\wxheading{Include files}

List the relevant include files, for example:

<wx/myclass.h>

\wxheading{Predefined objects}

List any predefined objects, such as:

{\bf wxNullMyClass}

\wxheading{See also}

List any relevant classes or topics, using \helpref.

\latexignore{\rtfignore{\wxheading{Members}}}

This generates the required heading for the member definitions.
Put the constructors first, then in alphabetical order, the other
members.

Here's an example of documentation for a member function:

         --------------------:x-----------------------

\membersection{wxBitmap::Create}\label{wxbitmapcreate}

\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height},
 \param{int}{ depth = -1}}

Creates a fresh bitmap. If the final argument is omitted, the display depth of
the screen is used.

\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type},
 \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}

Creates a bitmap from the given data, which can be of arbitrary type.

\wxheading{Parameters}

\docparam{width}{The width of the bitmap in pixels.}

\docparam{height}{The height of the bitmap in pixels.}

\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.}

\docparam{data}{Data whose type depends on the value of {\it type}.}

\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list
of possible values.}

\wxheading{Return value}

TRUE if the call succeeded, FALSE otherwise.

\wxheading{Remarks}

The first form works on all platforms. The portability of the second form depends on the
type of data.

\wxheading{See also}

\helpref{wxBitmap::wxBitmap}{wxbitmapconstr}

         --------------------:x-----------------------

Note the use of \docparam to document parameters; and the fact
that several overloaded forms of the same member function are
documented within the same \membersection.


Special forms:

- for a const member function use \constfunc{} instead of \const

- for a function without parameters use \func{...}{Function}{\void}

- but do NOT use \void for functions without return value, just "void"

- for a virtual/static member function use \func{virtual/static ...}

- omit the return type for constructors: \func{}{MyClass}{...}

- use \destruct macro for the destructors \func{}{\destruct{MyClass}}{\void}