fixed the anchor names for @section used in interface headers; documented the general rules used for its naming

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

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.
@@ -136,7 +136,6 @@ Start off with:
 
 /**
     @class wxMyClass
-    @wxheader{myclass.h}
 
     ...here goes the description...
 
@@ -173,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 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
@@ -204,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.
 
 /**
@@ -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.
-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:

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.
 
-    @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.

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).
 
-    @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
@@ -126,7 +126,7 @@
     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:

interface/wx/aui/framemanager.h

@@ -82,7 +82,7 @@ enum wxAuiManagerOption
     @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:

interface/wx/bmpbuttn.h

@@ -18,9 +18,9 @@
     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.

interface/wx/event.h

@@ -2433,7 +2433,7 @@ public:
     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

interface/wx/ptr_scpd.h

@@ -56,7 +56,7 @@
     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

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.
 
-    @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,