Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewritten technote for Doxygen documentation

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52037 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Francesco Montorsi
2008-02-24 15:48:20 +00:00
parent cba817acd4
commit 209f9b5e0e
1 changed files with 199 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

420
docs/tech/tn0003.txt
View File

@@ -5,99 +5,88 @@ 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.
wxWidgets uses Doxygen to process header input files with embedded
documentation in the form of C++ comments and output in HTML, and XML
(Doxygen itself can also output Latex, manpages, RTF, PDF etc).
See http://www.doxygen.org for more info about Doxygen.
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 you want to add documentation of a new class/function to the
existing manual in docs/doxygen, you need to create a new .h file,
e.g. myclass.h, under the interface folder, which contains the public
interface of the new class/function in C++ syntax.
The documentation can then be added in form of Doxygen comments to
the header file.
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 may also want to write a separate topic file,
e.g. docs/doxygen/overviews/myclass.h, and add the entry to
docs/doxygen/mainpages/topics.h.
You can generate a first pass at the myclass.tex file by
compiling and running HelpGen (utils/helpgen).
If applicable, also add an entry to docs/doxygen/mainpages/categories.h.
Running Tex2RTF
You can generate a first raw version of myclass.h simply taking its
"real" header and removing all the private and protected sections and
in general removing everything the user "shouldn't know": i.e. all things
which are implementation details.
Running Doxygen
===============
See the Tex2RTF documentation, but here are some forms:
First, make sure you have a recent version of Doxygen installed in your system.
For HTML:
tex2rtf manual.tex manual.htm -html -twice
1) cd wxWidgets/docs/doxygen
2) run ./regen.sh [Unix] or regen.bat [Windows]
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.
[TODO: istructions for generation of other formats]
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:
- Doxygen supports both commands in the form \command and @command;
all wxWidgets documentation uses the @command form.
See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp
for a list of possible values.
- strive to use dedicated Doxygen commands for e.g. notes, lists,
sections, etc. The "Special commands" page:
http://www.stack.nl/~dimitri/doxygen/commands.html
is your friend!
It's also very important to make a consistent use of the ALIASES
defined by wxWidgets' Doxyfile. Open that file for more info.
- 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.
- when you write true, false and NULL with their C++ semantic meaning,
then use the @true, @false and @NULL commands.
- leave a blank line between a heading and the next paragraph.
- separe different paragraphs with an empty comment line.
This is important otherwise Doxygen puts everything in the same
paragraph making the result less readable.
- test your changes, preferably converting the manual to WinHelp
format and running through the Windows help compiler to check
for missing labels, etc.
- leave a blank comment line between a @section, @subsection, @page
and the next paragraph.
- quote all '_' and '&' characters with a '\' character (e.g. "MY\_PROGRAM"
unless the '_' is inside a comment or a \begin{verbatim} ...
\end{verbatim} block
- test your changes, both reading the generated HTML docs and by looking
at the "doxygen.log" file produced (which will warn you about any
eventual mistake found in the comments).
- 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
- quote all the following characters prefixing them with a "@" char:
@ $ \ & < > # %
- when using a Doxygen alias like @itemdef{}, you need to escape the
comma characters which appear on the first argument, otherwise Doxygen
will interpret them as the marker of the end of the first argument and
the beginning of the second argument's text.
E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to
write:
@itemdef{wxEVT_MACRO(id\, func), This is the description of the macro}
Also note that you need to escape only the commas of the first argument's text;
second argument can have up to 10 commas unescaped (see the Doxyfile for the
trick used to implement this).
DON'T:
@@ -105,172 +94,161 @@ DON'T:
The manual is intended to be a fluent, English document and
not a collection of rough notes.
- use non-alphanumeric characters in labels.
- use non-alphanumeric characters in link anchors.
- 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 '-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
========================
Documentation comment for a class
=================================
Start off with:
\section{\class{wxMyClass}}\label{wxmyclass}
/**
* @class wxMyClass
* @headerfile wx/myclass.h
*
* ...here goes the description...
*
* @beginEventTable
* @event{EVT_SOME_EVENT(id, func)}:
* Description for EVT_SOME_EVENT.
* @endEventTable
*
* @beginStyleTable
* @style{wxSOME_STYLE}:
* Description for wxSOME_STYLE.
* ...
* @endStyleTable
*
* @beginExtraStyleTable
* @style{wxSOME_EXTRA_STYLE}:
* Description for wxSOME_EXTRA_STYLE.
* ...
* @endExtraStyleTable
*
* @library{wxbase}
* @stdobjects
* ...here goes the list of predefined instances...
*
* @seealso
* ...here goes the see-also list...
* you can make references to topic overviews or other
* manual pages using the @ref command
*/
(note that labels can only go on sections such as \chapter,
\section, \subsection, \membersection, but not on \wxheading, for
example.)
Note that the events, styles and extra-styles tables as
well as @stdobjects and @seealso lists are optional.
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.
Also note that you shouldn't use the Doxygen builtin @sa command
for the see-also list but rather the wxWidgets' alias @seealso
in this case.
Special forms:
Documentation comment for a function
====================================
- for a const member function use \constfunc{} instead of \const
Start off with:
- for a function without parameters use \func{...}{Function}{\void}
/**
* ...here goes the description of the function....
*
* @param param1
* ...here goes the description for the first parameter of this function
* @param param2
* ...here goes the description for the second parameter of this function
* ...
*
* @return
* ...here goes the description of what the function returns...
*
* @note ...here go any eventual notes about this function...
*
* @remarks ...here go any eventual remarks about this function...
*
* @sa ...here goes the see-also list...
*/
- but do NOT use \void for functions without return value, just "void"
Note that the @return, @note, @remarks, @sa commands are optional.
- for a virtual/static member function use \func{virtual/static ...}
Also note that unlike for class' description, you should use the doxygen
builtin @sa command here for see-also lists.
- omit the return type for constructors: \func{}{MyClass}{...}
The @param command has an optional attribute specifying the direction of
the attribute. Possible values are "in" and "out". E.g.
- use \destruct macro for the destructors \func{}{\destruct{MyClass}}{\void}
/**
* Copies bytes from a source memory area to a destination memory area,
* where both areas may not overlap.
* @param[out] dest The memory area to copy to.
* @param[in] src The memory area to copy from.
* @param[in] n The number of bytes to copy.
* @param[in,out] pmisc Used both as input and as output.
*/
void func(void *dest, const void *src, size_t n, void *pmisc);
- use \true and \false instead of true/TRUE/{\tt true}/...
- use \arg{paramname} to refer to the argument inside of the function
description
Documentation comment for a topic overview
==========================================
Topic overviews are stored inside the docs/doxygen/overviews folder
and are completely placed inside a single comment block in the form of:
/*!
@page overview_tname wxSomeStuff overview
This page provides an overview of the wxSomeStuff and related classes.
....
@li @ref overview_tname_intro
@li @ref overview_tname_details
...
<hr>
@section overview_tname_intro Introduction
...here goes the introduction to this topic...
@section overview_tname_details Details
...here go the details to this topic...
*/
Note that there is a convention in the anchor link names.
Doxygen in fact requires that for each @page, @section, @subsection, etc tag,
there is a corresponding link anchor.
The following conventions are used in wxWidgets doxygen comments:
1) all "main" pages of the manual (those which are placed in docs/doxygen/mainpages)
have link anchors which begin with "page_"
2) all topic overviews (those which are placed in docs/doxygen/overviews) have link
anchors which begin with "overview_"
3) all @section, @subsection, @subsubsection tags should have as link anchor name
the name of the parent section plus a specific word separed with an underscore; e.g.:
/*!
@page overview_tname wxSomeStuff overview
@section overview_tname_intro Introduction
@subsection overview_tname_intro_firstpart First part
@subsection overview_tname_intro_secondpart Second part
@subsubsection overview_tname_intro_secondpart_sub Second part subsection
@subsection overview_tname_intro_thirdpart Third part
@section overview_tname_details Details
...
*/
=== EOF ===
Author: FM (under the lines of the previous technote about tex2rtf)
Version: $Id$