fixed the anchor names for @section used in interface headers; documented the general...

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@56445 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt
index 180b193e1ff38299ea8e941ea542371600cdfb1c..e8553aed2d11f66fff501f9273e5c68dfa9d6211 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.


@@ -136,7 +136,6 @@ Start off with:
 
 /**
     @class wxMyClass
 
 /**
     @class wxMyClass

-    @wxheader{myclass.h}

 
     ...here goes the description...
 
 
     ...here goes the description...
 


@@ -173,9 +172,39 @@ Start off with:
          manual pages using the @ref command
 */
 
          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.
 
 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 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
 
 
 Documentation comment for a function


@@ -204,7 +233,7 @@ Start off with:
 
 Note that the @return, @note, @remarks, @see commands are optional.
 
 
 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.
 
 /**


@@ -250,7 +279,7 @@ 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:

diff --git a/interface/wx/archive.h b/interface/wx/archive.h
index ccec5851c5e96ecae8f90b299de4988e813feb23..88ca8cbf9617df544e96414db311d1fe93fa740b 100644 (file)
--- a/interface/wx/archive.h
+++ b/interface/wx/archive.h
@@ -162,7 +162,7 @@ public:
     These hold the meta-data (filename, timestamp, etc.), for entries
     in archive files such as zips and tars.
 
     These hold the meta-data (filename, timestamp, etc.), for entries
     in archive files such as zips and tars.
 

-    @section wxarchiveentry_nonseekable About non-seekable streams
+    @section archiveentry_nonseekable About non-seekable streams

 
     This information applies only when reading archives from non-seekable streams.
     When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry.
 
     This information applies only when reading archives from non-seekable streams.
     When the stream is seekable GetNextEntry() returns a fully populated wxArchiveEntry.

diff --git a/interface/wx/artprov.h b/interface/wx/artprov.h
index 33196e22eb2ead5e72133808780b72ccd67a17ca..0ab6d8cee63ee6eb9c49514eb5a08cce7df653c2 100644 (file)
--- a/interface/wx/artprov.h
+++ b/interface/wx/artprov.h
@@ -49,7 +49,7 @@
     (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider
      bitmaps is too small).
 
     (@note this is not yet really possible as of wxWidgets 2.3.3, the set of wxArtProvider
      bitmaps is too small).
 

-    @section wxartprovider_identify Identifying art resources
+    @section artprovider_identify Identifying art resources

 
     Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
     is used when requesting a resource from it. The ID is represented by wxArtID type
 
     Every bitmap and icon bundle are known to wxArtProvider under an unique ID that
     is used when requesting a resource from it. The ID is represented by wxArtID type


@@ -126,7 +126,7 @@
     The default theme is typically installed in @c /usr/share/icons/hicolor.
 
 
     The default theme is typically installed in @c /usr/share/icons/hicolor.
 
 

-    @section wxartprovider_clients Clients
+    @section artprovider_clients Clients

 
     Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function.
     It is represented by wxClientID type and can have one of these values:
 
     Client is the entity that calls wxArtProvider's GetBitmap or GetIcon function.
     It is represented by wxClientID type and can have one of these values:

diff --git a/interface/wx/aui/framemanager.h b/interface/wx/aui/framemanager.h
index 2f4b7c55915b2346fbc204b95852261fe16bb271..6e6d5ad581272802de1d74f345e723f60a76afa9 100644 (file)
--- a/interface/wx/aui/framemanager.h
+++ b/interface/wx/aui/framemanager.h
@@ -82,7 +82,7 @@ enum wxAuiManagerOption
     @endcode
 
 
     @endcode
 
 

-    @section wxauimanager_layers Layers, Rows and Directions, Positions
+    @section auimanager_layers Layers, Rows and Directions, Positions

 
     Inside wxAUI, the docking layout is figured out by checking several pane
     parameters. Four of these are important for determining where a pane will end up:
 
     Inside wxAUI, the docking layout is figured out by checking several pane
     parameters. Four of these are important for determining where a pane will end up:

diff --git a/interface/wx/bmpbuttn.h b/interface/wx/bmpbuttn.h
index 76847b6bd70fbd2e9592cfb3624d65cfb688bb8a..e2ad8cb936a6415854606415b4f900b9b6a067d8 100644 (file)
--- a/interface/wx/bmpbuttn.h
+++ b/interface/wx/bmpbuttn.h
@@ -18,9 +18,9 @@
     additional bitmaps for the selected state, unpressed focused state, and greyed-out
     state may be supplied.
 
     additional bitmaps for the selected state, unpressed focused state, and greyed-out
     state may be supplied.
 

-    @section wxbitmapbutton_states Button states
-    This class supports bitmaps for several different states:
+    @section bitmapbutton_states Button states

 
 

+    This class supports bitmaps for several different states:

     @li @b normal: this is the bitmap shown in the default state, it must be always
         valid while all the other bitmaps are optional and don't have to be set.
     @li @b disabled: bitmap shown when the button is disabled.
     @li @b normal: this is the bitmap shown in the default state, it must be always
         valid while all the other bitmaps are optional and don't have to be set.
     @li @b disabled: bitmap shown when the button is disabled.

diff --git a/interface/wx/event.h b/interface/wx/event.h
index e60017f376c583ab3ac528ffd1a59ab363c0228b..fdc99e5c8ed9f4768b69ed819a986dfa41ae36d0 100644 (file)
--- a/interface/wx/event.h
+++ b/interface/wx/event.h
@@ -2433,7 +2433,7 @@ public:
     events and use the event table macros mentioned below only for the scrollbar-like
     controls.
 
     events and use the event table macros mentioned below only for the scrollbar-like
     controls.
 

-    @section wxscrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED
+    @section scrollevent_diff The difference between EVT_SCROLL_THUMBRELEASE and EVT_SCROLL_CHANGED

 
     The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
     using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed
 
     The EVT_SCROLL_THUMBRELEASE event is only emitted when actually dragging the thumb
     using the mouse and releasing it (This EVT_SCROLL_THUMBRELEASE event is also followed

diff --git a/interface/wx/ptr_scpd.h b/interface/wx/ptr_scpd.h
index 4d6e47f2551095d4302ec51a843fa579bf57550e..2434a6dced43954ec0798950e8f2ade6a4d1bbc5 100644 (file)
--- a/interface/wx/ptr_scpd.h
+++ b/interface/wx/ptr_scpd.h
@@ -56,7 +56,7 @@
     theCharObj[0] = "!";
     @endcode
 
     theCharObj[0] = "!";
     @endcode
 

-    @section wxscopedptr_newpointers Declaring new smart pointer types
+    @section scopedptr_newpointers Declaring new smart pointer types

 
     To declare the smart pointer class @c CLASSNAME containing pointes to
     a (possibly incomplete) type @c TYPE you should use
 
     To declare the smart pointer class @c CLASSNAME containing pointes to
     a (possibly incomplete) type @c TYPE you should use

diff --git a/interface/wx/vscroll.h b/interface/wx/vscroll.h
index 13a13229fb144996109fab21cdda915b6f60c98a..a7164bad0924587617f6254e2bbfa02ef2030b75 100644 (file)
--- a/interface/wx/vscroll.h
+++ b/interface/wx/vscroll.h
@@ -629,7 +629,7 @@ public:
     shifted so the first visible row always appears at the point (0, 0) in
     physical as well as logical coordinates.
 
     shifted so the first visible row always appears at the point (0, 0) in
     physical as well as logical coordinates.
 

-    @section wxWidgets 2.8 Compatibility Functions
+    @section vscrolledwindow_compat wxWidgets 2.8 Compatibility Functions

 
     The following functions provide backwards compatibility for applications
     originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,
 
     The following functions provide backwards compatibility for applications
     originally built using wxVScrolledWindow in 2.6 or 2.8. Originally,