X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a51ea7f13d66ab19f493b1927c1d7b13f46a89bd..dc735b4085a71ba204bca6a61bd35e99d1e13ea6:/docs/tech/tn0003.txt diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt index f9f142bd0b..7feee05b54 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. @@ -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. -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 @@ -32,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 @@ -49,6 +58,7 @@ DO: - 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: @@ -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. -- 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. @@ -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. & 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 @@ -86,9 +97,19 @@ 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; + => 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: @@ -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. - See the Doxyfile for more info. + See the Doxyfile.inc for more info. Documentation comment for a class @@ -114,44 +135,76 @@ Documentation comment for a class 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 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 @@ -160,30 +213,27 @@ Documentation comment for a function 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. /** @@ -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. -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.: /*! @@ -261,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$