X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/209f9b5e0e5e78b526df31040d2a9187c57758ca..2e18fe7139558b3cb592a04a4e4668319a966ebf:/docs/tech/tn0003.txt
diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt
index 4428be7db0..f81beb4074 100644
--- a/docs/tech/tn0003.txt
+++ b/docs/tech/tn0003.txt
@@ -10,7 +10,7 @@ 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 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.
@@ -21,7 +21,8 @@ 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.
-If applicable, also add an entry to docs/doxygen/mainpages/categories.h.
+If applicable, also add an entry to one of the docs/doxygen/mainpages/cat_*.h
+files.
You can generate a first raw version of myclass.h simply taking its
"real" header and removing all the private and protected sections and
@@ -32,14 +33,22 @@ which are implementation details.
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
@@ -49,6 +58,7 @@ DO:
- Doxygen supports both commands in the form \command and @command;
all wxWidgets documentation uses the @command form.
+ Follow strictly this rule.
- strive to use dedicated Doxygen commands for e.g. notes, lists,
sections, etc. The "Special commands" page:
@@ -60,7 +70,7 @@ DO:
- 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.
@@ -75,6 +85,9 @@ DO:
@ $ \ & < > # %
+ unless they appear inside a @code or @verbatim section
+ (you can also use HTML-style escaping, e.g. & rather than @ escaping)
+
- 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
@@ -84,9 +97,19 @@ DO:
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 () suffix to refer to function members of the same class you're
+ documenting or to refer to global functions or macros;
+ => 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.
DON'T:
@@ -96,6 +119,15 @@ DON'T:
- use non-alphanumeric characters in link anchors.
+- use Doxygen @b @c @e commands when referring to more than a single word;
+ in that case you need to use the ..., ..., ...
+ HTML-style tags instead
+
+- use HTML style tags for creation of tables or lists.
+ Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and
+ @beginDefList, @itemdef, @endDefList, etc.
+ See the Doxyfile.inc for more info.
+
Documentation comment for a class
=================================
@@ -103,44 +135,76 @@ Documentation comment for a class
Start off with:
/**
- * @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
- */
+ @class wxMyClass
+
+ ...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}
+ @category{cat_shortcut}
+
+ @nativeimpl{wxgtk, wxmsw, ...}
+ @onlyfor{wxgtk, wxmsw, ...}
+
+ @appearance{button.png}
+
+ @stdobjects
+ ...here goes the list of predefined instances...
+
+ @see ...here goes the see-also list...
+ you can make references to topic overviews or other
+ manual pages using the @ref command
+*/
+
+Note that everything *except* the @class, @library and @category
+commands are optionals.
-Note that the events, styles and extra-styles tables as
-well as @stdobjects and @seealso lists are optional.
+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
+*/
-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.
Documentation comment for a function
@@ -149,30 +213,27 @@ Documentation comment for a function
Start off with:
/**
- * ...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...
- */
+ ...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
+ ...
-Note that the @return, @note, @remarks, @sa commands are optional.
+ @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...
+
+ @see ...here goes the see-also list...
+ */
-Also note that unlike for class' description, you should use the doxygen
-builtin @sa command here for see-also lists.
+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.
/**
@@ -218,19 +279,20 @@ and are completely placed inside a single comment block in the form of:
*/
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.:
/*!
@@ -250,5 +312,5 @@ The following conventions are used in wxWidgets doxygen comments:
=== 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$