Ensure we pass the correct type of string to EscapeFileNameCharsInURL in wxWebViewArc...

[wxWidgets.git] / docs / tech / tn0003.txt

diff --git a/docs/tech/tn0003.txt b/docs/tech/tn0003.txt
index 57cab689b1e4113eaf4e5f1270c800c0091a1314..f81beb40748275b010b686e545ad797137a9d41f 100644 (file)
--- a/docs/tech/tn0003.txt
+++ b/docs/tech/tn0003.txt
@@ -1,80 +1,115 @@
-                     Adding wxWindows class documentation
+                     Adding wxWidgets class documentation

                      ====================================
 
 This note is aimed at people wishing to add documentation for a
                      ====================================
 
 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.
 
 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.
+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.

 
 

-Running Tex2RTF
-===============
-
-See the Tex2RTF documentation, but here are some forms:
+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.

 
 

-For HTML:

 
 

-  tex2rtf manual.tex manual.htm -html -twice
+Running Doxygen
+===============

 
 

-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.
+First, make sure you have a recent version of Doxygen installed in your system
+(you'll need Doxygen >= 1.5.7).

 
 

-For WinHelp RTF:
+On Unix:

 
 

-  tex2rtf manual.tex manual.rtf -winhelp -twice
+  1) run wxWidgets/docs/doxygen/regen.sh [format-to-generate]

 
 

-For Word RTF:
+On Windows:
+  1) cd wxWidgets/docs/doxygen
+  2) run regen.bat [format-to-generate]

 
 

-  tex2rtf manual.tex manual.rtf -rtf -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".

 
 

-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).
+The output of Doxygen is all placed in the wxWidgets/docs/doxygen/out folder.

 
 

-src/msw/makefile.vc contains targets for generating various
-formats of documentation. You may like to do something similar if
-writing your own manual.

 
 Important Dos and Don'ts
 ========================
 
 DO:
 
 
 Important Dos and Don'ts
 ========================
 
 DO:
 

-- 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:
+- 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:
+    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.
+
+- when you write true, false and NULL with their C++ semantic meaning,
+  then use the @true, @false and @NULL commands.
+
+- separate different paragraphs with an empty comment line.
+  This is important otherwise Doxygen puts everything in the same
+  paragraph making the result less readable.
+
+- leave a blank comment line between a @section, @subsection, @page
+  and the next paragraph.
+
+- 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).
+
+- quote all the following characters prefixing them with a "@" char:
+
+         @  $  \  &  <  >  #  %

 
 

-  See \helpref{wxBitmap::wxBitmap}{wxbitmapconstr}\rtfsp
-  for a list of possible values.
+  unless they appear inside a @code or @verbatim section
+  (you can also use HTML-style escaping, e.g. &amp; rather than @ escaping)

 
 

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

 
 

-- leave a blank line between a heading and the next paragraph.
+  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}

 
 

-- test your changes, preferably converting the manual to WinHelp
-  format and running through the Windows help compiler to check
-  for missing labels, etc.
+  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:
 
 
 DON'T:
 


@@ -82,125 +117,200 @@ DON'T:
   The manual is intended to be a fluent, English document and
   not a collection of rough notes.
 
   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 <b>...</b>, <tt>...</tt>, <em>...</em>
+  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.

 
 

-Troubleshooting
-===============

 
 

-Please see the troubleshooting section in the Tex2RTF manual, but
-here is one important tip:
+Documentation comment for a class
+=================================

 
 

-  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.
+Start off with:

 
 

-   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.
+/**
+    @class wxMyClass

 
 

-   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.
+    ...here goes the description...

 
 

-Elements in a class file
-========================
+    @beginEventTable
+    @event{EVT_SOME_EVENT(id, func)}:
+            Description for EVT_SOME_EVENT.
+    @endEventTable

 
 

-Start off with:
+    @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.

 
 

-<wx/myclass.h>
+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-----------------------
+ <hr>

 
 

-\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$