(Doxygen itself can also output Latex, manpages, RTF, PDF etc).
See http://www.doxygen.org for more info about Doxygen.
-If you want to add documentation of a new class/function to the
+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.
Running Doxygen
===============
-First, make sure you have a recent version of Doxygen installed in your system.
+First, make sure you have a recent version of Doxygen installed in your system
+(you'll need Doxygen >= 1.5.7).
-For HTML:
+On Unix:
+ 1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate]
+
+On Windows:
1) cd wxWidgets/docs/doxygen
- 2) run ./regen.sh [Unix] or regen.bat [Windows]
+ 2) run regen.bat [format-to-generate]
+
+If you don't specify which format to [re]generate, all output formats will
+be enabled. Possible values for [format-to-generate] are: "html", "chm", "latex",
+"xml" and "all".
-[TODO: istructions for generation of other formats]
+The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder.
Important Dos and Don'ts
- when you write true, false and NULL with their C++ semantic meaning,
then use the @true, @false and @NULL commands.
-- separe different paragraphs with an empty comment line.
+- separate different paragraphs with an empty comment line.
This is important otherwise Doxygen puts everything in the same
paragraph making the result less readable.
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).
+ 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).
- for linking use one of:
=> the @ref command to refer to topic overviews;
=> the classname:: operator to refer to functions of classes different
from the one you're documenting;
=> the :: prefix to refer to global variables (e.g. ::wxEmptyString).
- Class names are auto-linked by Doxygen without the need of any explicit command.
+ Class names are auto-linked by Doxygen without the need of any explicit
+ command.
DON'T:
/**
@class wxMyClass
- @wxheader{myclass.h}
...here goes the description...
manual pages using the @ref command
*/
-Note that everything *except* the @class, @wxheader, @library and @category
+Note that everything *except* the @class, @library and @category
commands are optionals.
+Also note that if you use @section and @subsection in the class description
+(at the beginning), you should use as the section's anchor name "xxxx_yyyy"
+where "xxxx" is the class name without the initial "wx" in lowercase
+and "yyyy" is a lowercase word which uniquely identifies that section.
+E.g.:
+
+/**
+ @class wxMyClass
+
+ This class does not exist really and is only used as an example
+ of best documentation practices.
+
+ @section myclass_special Special functions of this class
+
+ This section describes the functions whose usage is reserved for
+ wxWidgets internal mechanisms... etc etc...
+
+
+ @section myclass_custom Customizing wxMyClass
+
+ What if you want to customize this powerful class?
+ First you should do this and that, etc etc...
+
+
+ @library{wxbase}
+ @category{misc}
+
+ @see wxMyOtherClass
+*/
+
Documentation comment for a function
Note that the @return, @note, @remarks, @see commands are optional.
-The @param command has an optional attribute specifying the direction of
+The @param command has an optional attribute specifying the direction of
the attribute. Possible values are "in" and "out". E.g.
/**
*/
Note that there is a convention in the anchor link names.
-Doxygen in fact requires that for each @page, @section, @subsection, etc tag,
+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_"
+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_"
+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.:
+3) all @section, @subsection, @subsubsection tags should have as link anchor
+ name the name of the parent section plus a specific word separated with an
+ underscore; e.g.:
/*!
=== EOF ===
-Author: FM (under the lines of the previous technote about tex2rtf)
+Author: FM (along the lines of the previous technote about tex2rtf)
Version: $Id$
projects / wxWidgets.git / blobdiff