- Adding wxWindows class documentation
+ Adding wxWidgets 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
+class to either the main wxWidgets manual, or to their own
manual.
-wxWindows uses Tex2RTF to process Latex-like input files (.tex)
+wxWidgets 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
+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.
+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
-wxWindows manual or a contribution. Contribution documentation
+wxWidgets manual or a contribution. Contribution documentation
normally goes in the contrib/docs hierarchy, with the source
going in a latex/mycontrib subdirectory.
tex2rtf manual.tex manual.rtf -rtf -twice -interactive
NOTE: You must be using the latest tex2rtf which was released with
-v2.2.0 of wxWindowsto use the -interactive switch
+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
-wxWindows manual. To futher speed-up HTML help books loading
+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
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 '-checkcurlybraces'
+ 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.
- 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,
+ 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.
line comment character (%) to see whether it was that file that
caused the problem.
+ When making changes/additions to the documentation, always use
+ the '-checkcurlybraces' 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
========================
the screen is used.
\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type},
- \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}}
+ \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = $-1$}}
Creates a bitmap from the given data, which can be of arbitrary type.
\wxheading{Return value}
-TRUE if the call succeeded, FALSE otherwise.
+\true if the call succeeded, \false otherwise.
\wxheading{Remarks}
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
projects / wxWidgets.git / blobdiff