remove ancient SetModal(), it was deprecated long ago and is not present in wxMSW...

[wxWidgets.git] / docs / tech / tn0003.txt

diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt
index f9f142bd0bb18c72bbee629e35b5a43a4b04855f..f81beb40748275b010b686e545ad797137a9d41f 100644 (file)
--- 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.
 
 (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.
 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.
 
 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
 
 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
 ===============
 
 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
   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
 
 
 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.
 
 - 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:
 
 - 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.
 
 - 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.
 
   This is important otherwise Doxygen puts everything in the same
   paragraph making the result less readable.
 


@@ -75,7 +85,8 @@ DO:
 
          @  $  \  &  <  >  #  %
 
 
          @  $  \  &  <  >  #  %
 

-  unless they appear inside a @code or @verbatim section.
+  unless they appear inside a @code or @verbatim section
+  (you can also use HTML-style escaping, e.g. &amp; 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
 
 - when using a Doxygen alias like @itemdef{}, you need to escape the
   comma characters which appear on the first argument, otherwise Doxygen


@@ -86,9 +97,19 @@ DO:
        write:
             @itemdef{wxEVT_MACRO(id\, func), This is the description of the macro}
 
        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:
 
 
 DON'T:
 


@@ -105,7 +126,7 @@ DON'T:
 - use HTML style tags for creation of tables or lists.
   Use wx aliases instead like @beginTable, @row2col, @row3col, @endTable and
   @beginDefList, @itemdef, @endDefList, etc.
 - 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 for more info.
+  See the Doxyfile.inc for more info.

 
 
 Documentation comment for a class
 
 
 Documentation comment for a class


@@ -114,44 +135,76 @@ Documentation comment for a class
 Start off with:
 
 /**
 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}

 
 

-Note that the events, styles and extra-styles tables as
-well as @stdobjects and @seealso lists are optional.
+    @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.
+
+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
 
 
 Documentation comment for a function


@@ -160,30 +213,27 @@ Documentation comment for a function
 Start off with:
 
 /**
 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.
 
 /**
 the attribute. Possible values are "in" and "out". E.g.
 
 /**


@@ -229,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.
 */
 
 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:
 
 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.:

 
 /*!
 
 
 /*!
 


@@ -261,5 +312,5 @@ The following conventions are used in wxWidgets doxygen comments:
 
 === EOF ===
 
 
 === 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$
 Version: $Id$