X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/478c80536375745735c3f42f4051ab407b93ab28..7a36d9c7c1a077ba7e05c248bcf19c4c9bb1356f:/docs/tech/tn0003.txt

diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt
index 0f399147d4..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.
@@ -33,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
@@ -62,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.
 
@@ -89,9 +97,9 @@ 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;
@@ -100,7 +108,8 @@ DO:
      => 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:
 
@@ -127,7 +136,6 @@ Start off with:
 
 /**
     @class wxMyClass
-    @wxheader{myclass.h}
 
     ...here goes the description...
 
@@ -164,9 +172,39 @@ Start off with:
          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
@@ -195,7 +233,7 @@ Start off with:
 
 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.
 
 /**
@@ -241,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.:
 
 /*!
 
@@ -273,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$