From: Francesco Montorsi Date: Sun, 19 Oct 2008 15:30:20 +0000 (+0000) Subject: fixed the anchor names for @section used in interface headers; documented the general... X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/3a74a290a9fcfafd93fd1a23e6857ad60836cb9d 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 --- diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt index 180b193e1f..e8553aed2d 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. @@ -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: diff --git a/interface/wx/archive.h b/interface/wx/archive.h index ccec5851c5..88ca8cbf96 100644 --- 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. - @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. diff --git a/interface/wx/artprov.h b/interface/wx/artprov.h index 33196e22eb..0ab6d8cee6 100644 --- 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). - @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: diff --git a/interface/wx/aui/framemanager.h b/interface/wx/aui/framemanager.h index 2f4b7c5591..6e6d5ad581 100644 --- a/interface/wx/aui/framemanager.h +++ b/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: diff --git a/interface/wx/bmpbuttn.h b/interface/wx/bmpbuttn.h index 76847b6bd7..e2ad8cb936 100644 --- 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. - @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. diff --git a/interface/wx/event.h b/interface/wx/event.h index e60017f376..fdc99e5c8e 100644 --- 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. - @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 diff --git a/interface/wx/ptr_scpd.h b/interface/wx/ptr_scpd.h index 4d6e47f255..2434a6dced 100644 --- a/interface/wx/ptr_scpd.h +++ b/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 diff --git a/interface/wx/vscroll.h b/interface/wx/vscroll.h index 13a13229fb..a7164bad09 100644 --- 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. - @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,