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
- 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:
@ $ \ & < > # %
+ 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
will interpret them as the marker of the end of the first argument and
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:
- use jargon, such as 'gonna', or omit the definite article.
- use non-alphanumeric characters in link anchors.
+- use Doxygen @b @c @e commands when referring to more than a single word;
+ in that case you need to use the <b>...</b>, <tt>...</tt>, <em>...</em>
+ HTML-style tags instead
+
+- 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.inc for more info.
+
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
+ @wxheader{myclass.h}
+
+ ...here goes the description...
-Note that the events, styles and extra-styles tables as
-well as @stdobjects and @seealso lists are optional.
+ @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}
+
+ @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, @wxheader, @library and @category
+commands are optionals.
-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
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....
-Note that the @return, @note, @remarks, @sa commands are optional.
+ @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...
+
+ @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 attribute. Possible values are "in" and "out". E.g.
projects / wxWidgets.git / blobdiff