X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b74d0665b597582e5d2c3cad413585c0f2101490..89b3361ec25cf1e6d255b14c7633d8375646e4fb:/docs/tech/tn0003.txt?ds=sidebyside diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt index e193c50fe1..f81beb4074 100644 --- a/docs/tech/tn0003.txt +++ b/docs/tech/tn0003.txt @@ -1,101 +1,115 @@ - Adding wxWindows class documentation + Adding wxWidgets class documentation ==================================== This note is aimed at people wishing to add documentation for a -class to either the main wxWindows manual, or to their own +class to either the main wxWidgets manual, or to their own manual. -wxWindows uses Tex2RTF to process Latex-like input files (.tex) -and output in HTML, WinHelp RTF and Word RTF. Tex2RTF is provided -in the wxWindows distribution and in the CVS archive, under -utils/tex2rtf. Please start by perusing the Tex2RTF manual. +wxWidgets uses Doxygen to process header input files with embedded +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 adding to the existing manual in docs/latex/wx, you need to -create a new .tex file, e.g. myclass.tex, and add it to the -list of classes in classes.tex (in strict alphabetical order). -You may also want to write a separate topic file, e.g. tmyclass.tex, -and add the entry to topics.tex. Also, if applicable, and an entry -to category.tex. +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. +The documentation can then be added in form of Doxygen comments to +the header file. -If compiling a separate manual, copy an existing set of files from the -wxWindows manual or a contribution. Contribution documentation -normally goes in the contrib/docs hierarchy, with the source -going in a latex/mycontrib subdirectory. +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. -You can generate a first pass at the myclass.tex file by -compiling and running HelpGen (utils/helpgen). +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 +in general removing everything the user "shouldn't know": i.e. all things +which are implementation details. -Running Tex2RTF -=============== -See the Tex2RTF documentation, but here are some forms: +Running Doxygen +=============== -For HTML: +First, make sure you have a recent version of Doxygen installed in your system +(you'll need Doxygen >= 1.5.7). - tex2rtf manual.tex manual.htm -html -twice +On Unix: -Use of -twice allows Tex2RTF to resolve references. Note that -if both filenames are given (first two parameters on the command -line) then Tex2RTF will run in non-interactive mode. + 1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate] -For WinHelp RTF: +On Windows: + 1) cd wxWidgets/docs/doxygen + 2) run regen.bat [format-to-generate] - tex2rtf manual.tex manual.rtf -winhelp -twice +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". -For Word RTF: +The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder. - tex2rtf manual.tex manual.rtf -rtf -twice -If you wish to have a GUI display show the status of what is happening -as the conversion is happening, use the '-interactive' command line -parameter, and then choose FILE|GO from the menu. For example: +Important Dos and Don'ts +======================== - tex2rtf manual.tex manual.rtf -rtf -twice -interactive +DO: -NOTE: You must be using the latest tex2rtf which was released with -v2.2.0 of wxWindows to use the -interactive switch +- Doxygen supports both commands in the form \command and @command; + all wxWidgets documentation uses the @command form. + Follow strictly this rule. -If you wish to generate documentation for wxHTML Help Viewer -(or Windows HTML Help), set htmlWorkshopFiles to true in your -tex2rtf.ini file. See also the wxHTML Notes section in the -wxWindows manual. To futher speed-up HTML help books loading -in your application, you may use hhp2cached (utils/hhp2cached). +- strive to use dedicated Doxygen commands for e.g. notes, lists, + sections, etc. The "Special commands" page: + http://www.stack.nl/~dimitri/doxygen/commands.html + is your friend! + It's also very important to make a consistent use of the ALIASES + defined by wxWidgets' Doxyfile. Open that file for more info. -src/msw/makefile.vc contains targets for generating various -formats of documentation. You may like to do something similar if -writing your own manual. +- when you write true, false and NULL with their C++ semantic meaning, + then use the @true, @false and @NULL commands. -Important Dos and Don'ts -======================== +- separate different paragraphs with an empty comment line. + This is important otherwise Doxygen puts everything in the same + paragraph making the result less readable. -DO: +- leave a blank comment line between a @section, @subsection, @page + and the next paragraph. -- put a space (or \rtfsp) at the end of a line or start of a line where - a command ends or starts the line. Otherwise, spaces will be - omitted in Word or WinHelp RTF. For example: +- test your changes, both reading the generated HTML docs and by looking + at the "doxygen.log" file produced (which will warn you about any + eventual mistake found in the comments). - See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp - for a list of possible values. +- quote all the following characters prefixing them with a "@" char: -- leave a blank line at the end of the class file. This is - important, or the Word RTF table of contents will be messed up. + @ $ \ & < > # % -- leave a blank line between a heading and the next paragraph. + unless they appear inside a @code or @verbatim section + (you can also use HTML-style escaping, e.g. & rather than @ escaping) -- test your changes, preferably converting the manual to WinHelp - format and running through the Windows help compiler to check - for missing labels, etc. +- 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 + the beginning of the second argument's text. -- quote all '_' characters with a '\' character (e.g. "MY\_PROGRAM" - unless the '_' is inside a comment or a \begin{verbatim} ... - \end{verbatim} block + E.g. if you want to define the item "wxEVT_MACRO(id, func)" you need to + write: + @itemdef{wxEVT_MACRO(id\, func), This is the description of the macro} -- check that your changes/additions to any TEX documentation - compiles before checking it in! Use the '-checkcurleybrace' - and '-checksyntax' commandline parameters (or the OPTIONS menu - if running in GUI mode) to check for some of the more common - mistakes. See TROUBLESHOOTING below for more details + 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: @@ -103,153 +117,200 @@ DON'T: The manual is intended to be a fluent, English document and not a collection of rough notes. -- use non-alphanumeric characters in labels. +- use non-alphanumeric characters in link anchors. -- use incompatible Latex syntax, such as {\it \bf word} (use a pair - of braces for each formatting command). +- use Doxygen @b @c @e commands when referring to more than a single word; + in that case you need to use the ..., ..., ... + HTML-style tags instead -- leave multiple consecutive blank lines, or blank lines between - \items in a list. +- 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. -- use \verb$....$ syntax. Instead use \tt{....} syntax -- add the following tokens anywhere except on a line by themselves: - \begin{verbatim} - \begin{toocomplex} - \end{verbatim} - \end{toocomplex} - \verb - \begin{comment} - \end{comment} - \verbatiminput - \par - \input - \helpinput - \include - +Documentation comment for a class +================================= -Troubleshooting -=============== +Start off with: -Please see the troubleshooting section in the Tex2RTF manual, but -here is one important tip: - - If you get a "Macro not found: \end{document}" error, - this is a spurious side-effect of an earlier error, usually an - incorrect number of arguments to a command. The location of the - true error is then anywhere in the document. - - To home in on the error, try putting \begin{comment}...\end{comment} - around much of the document, and then move the \begin{comment} - line down until the error manifests itself again. Note that - you can abort Tex2RTF after the syntax error stage by clicking - on the close button, so you don't have to wait while the whole - document is processed. - - Before looking at a file in detail, you can comment out the - \input{myclass.tex} line in classes.tex using the single - line comment character (%) to see whether it was that file that - caused the problem. - - When making changes/additions to the documentation, always use - the '-checkcurleybraces' and '-checksyntax' commandline parameters - (or turn these options on in the GUI version via the OPTIONS menu - choice), BEFORE checking in your changes. These two debugging - options will catch many of the more common mistakes that are made - while writing documents, plus they will catch some of the uses - of TeX that are correct syntax-wise, but that tex2rtf cannot - handle properly, and report the problems (usually along with - a filename and line number that they occur in!) in the programs - output window (GUI mode). - -Elements in a class file -======================== +/** + @class wxMyClass -Start off with: + ...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} + + @nativeimpl{wxgtk, wxmsw, ...} + @onlyfor{wxgtk, wxmsw, ...} + + @appearance{button.png} -\section{\class{wxMyClass}}\label{wxmyclass} + @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 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 +==================================== + +Start off with: -(note that labels can only go on sections such as \chapter, -\section, \subsection, \membersection, but not on \wxheading, for -example.) +/** + ...here goes the description of the function.... -Describe the class briefly. + @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 + ... -Then there are several \wxheading sections: + @return + ...here goes the description of what the function returns... -\wxheading{Derived from} + @note ...here go any eventual notes about this function... -List the base classes, with line breaks following each one (\\) -except the last. + @remarks ...here go any eventual remarks about this function... -\wxheading{Include files} + @see ...here goes the see-also list... + */ -List the relevant include files, for example: +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. -\wxheading{Predefined objects} +/** + * Copies bytes from a source memory area to a destination memory area, + * where both areas may not overlap. + * @param[out] dest The memory area to copy to. + * @param[in] src The memory area to copy from. + * @param[in] n The number of bytes to copy. + * @param[in,out] pmisc Used both as input and as output. + */ +void func(void *dest, const void *src, size_t n, void *pmisc); -List any predefined objects, such as: -{\bf wxNullMyClass} +Documentation comment for a topic overview +========================================== -\wxheading{See also} +Topic overviews are stored inside the docs/doxygen/overviews folder +and are completely placed inside a single comment block in the form of: -List any relevant classes or topics, using \helpref. +/*! -\latexignore{\rtfignore{\wxheading{Members}}} + @page overview_tname wxSomeStuff overview -This generates the required heading for the member definitions. -Put the constructors first, then in alphabetical order, the other -members. + This page provides an overview of the wxSomeStuff and related classes. + .... -Here's an example of documentation for a member function: + @li @ref overview_tname_intro + @li @ref overview_tname_details + ... - --------------------:x----------------------- +
-\membersection{wxBitmap::Create}\label{wxbitmapcreate} -\func{virtual bool}{Create}{\param{int}{ width}, \param{int}{ height}, - \param{int}{ depth = -1}} + @section overview_tname_intro Introduction -Creates a fresh bitmap. If the final argument is omitted, the display depth of -the screen is used. + ...here goes the introduction to this topic... -\func{virtual bool}{Create}{\param{void*}{ data}, \param{int}{ type}, - \param{int}{ width}, \param{int}{ height}, \param{int}{ depth = -1}} -Creates a bitmap from the given data, which can be of arbitrary type. + @section overview_tname_details Details -\wxheading{Parameters} + ...here go the details to this topic... -\docparam{width}{The width of the bitmap in pixels.} +*/ -\docparam{height}{The height of the bitmap in pixels.} +Note that there is a convention in the anchor link names. +Doxygen in fact requires that for each @page, @section, @subsection, etc tag, +there is a corresponding link anchor. -\docparam{depth}{The depth of the bitmap in pixels. If this is -1, the screen depth is used.} +The following conventions are used in wxWidgets doxygen comments: -\docparam{data}{Data whose type depends on the value of {\it type}.} +1) all "main" pages of the manual (those which are placed in + docs/doxygen/mainpages) have link anchors which begin with "page_" -\docparam{type}{A bitmap type identifier - see \helpref{wxBitmap::wxBitmap}{wxbitmapconstr} for a list -of possible values.} +2) all topic overviews (those which are placed in docs/doxygen/overviews) have + link anchors which begin with "overview_" -\wxheading{Return value} +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.: -TRUE if the call succeeded, FALSE otherwise. +/*! -\wxheading{Remarks} + @page overview_tname wxSomeStuff overview -The first form works on all platforms. The portability of the second form depends on the -type of data. + @section overview_tname_intro Introduction + @subsection overview_tname_intro_firstpart First part + @subsection overview_tname_intro_secondpart Second part + @subsubsection overview_tname_intro_secondpart_sub Second part subsection + @subsection overview_tname_intro_thirdpart Third part -\wxheading{See also} + @section overview_tname_details Details + ... -\helpref{wxBitmap::wxBitmap}{wxbitmapconstr} +*/ - --------------------:x----------------------- -Note the use of \docparam to document parameters; and the fact -that several overloaded forms of the same member function are -documented within the same \membersection. +=== EOF === +Author: FM (along the lines of the previous technote about tex2rtf) +Version: $Id$