fc2171bd4c
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@27090 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
277 lines
8.7 KiB
Plaintext
277 lines
8.7 KiB
Plaintext
Adding wxWidgets class documentation
|
|
====================================
|
|
|
|
This note is aimed at people wishing to add documentation for a
|
|
class to either the main wxWidgets manual, or to their own
|
|
manual.
|
|
|
|
wxWidgets uses Tex2RTF to process Latex-like input files (.tex)
|
|
and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided
|
|
in the wxWidgets distribution and in the CVS archive, under
|
|
utils/tex2rtf. Please start by perusing the Tex2RTF manual.
|
|
See http://www.wxwidgets.org/tex2rtf/index.htm for a browseable
|
|
manual and binaries for specific platforms.
|
|
|
|
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. If applicable, also add an entry
|
|
to category.tex.
|
|
|
|
If compiling a separate manual, copy an existing set of files from the
|
|
wxWidgets 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 wxWidgets 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
|
|
wxWidgets manual. To further 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 '_' and '&' 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 '-checkcurleybraces'
|
|
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}
|
|
|
|
- use \true and \false instead of true/TRUE/{\tt true}/...
|
|
|
|
- use \arg{paramname} to refer to the argument inside of the function
|
|
description
|