mods for doxygen-0.49-991003

1 files changed, 116 insertions, 8 deletions

diff --git a/doc/commands.doc b/doc/commands.doc
index 5965aaf..d391c2c 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -70,12 +70,14 @@ documentation:
 <li> \refitem cmdfile \file 
 <li> \refitem cmdfn \fn 
 <li> \refitem cmdhtmlonly \htmlonly
+<li> \refitem cmdimage \image 
 <li> \refitem cmdinclude \include 
 <li> \refitem cmdingroup \ingroup 
 <li> \refitem cmdinternal \internal
 <li> \refitem cmdlatexonly \latexonly
 <li> \refitem cmdline \line 
 <li> \refitem cmdlink \link 
+<li> \refitem cmdmainpage \mainpage 
 <li> \refitem cmdnamespace \namespace
 <li> \refitem cmdoverload \overload 
 <li> \refitem cmdpage \page 
@@ -84,6 +86,7 @@ documentation:
 <li> \refitem cmdref \ref 
 <li> \refitem cmdrelates \relates 
 <li> \refitem cmdreturn \return 
+<li> \refitem cmdretval \retval
 <li> \refitem cmdsa \sa 
 <li> \refitem cmdsection \section 
 <li> \refitem cmdskip \skip 
@@ -287,6 +290,38 @@ Doxygen. Unrecognized commands are treated as normal text.
   All text after a \c \internal command is ignored.
 
 <hr>
+\subsection cmdmainpage \mainpage [(title)]
+
+  \addindex \mainpage
+
+  If the \\mainpage command is placed in a comment block the 
+  block is used to customize the index page (in HTML) or
+  the first chapter (in \f$\mbox{\LaTeX}\f$). 
+
+  The title argument is optional and replaces the default title that
+  doxygen normally generates.
+
+  Here is an example:
+\verbatim
+/*! \mainpage My Personal Index Page
+ *
+ * \section intro Introduction
+ *
+ * This is the introduction.
+ *
+ * \section install Installation
+ *
+ * \subsection step1 Step 1: Opening the box
+ *  
+ * etc...
+ */
+\endverbatim
+
+ \sa section \ref cmdsection "\\section", 
+     section \ref cmdsubsection "\\subsection" and 
+     section \ref cmdpage "\\page".
+
+<hr>
 \subsection cmdnamespace \namespace <name> 
 
   \addindex \namespace
@@ -338,6 +373,15 @@ Doxygen. Unrecognized commands are treated as normal text.
   Click <a href="$(DOXYGEN_DOCDIR)/examples/page/html/pages.html">here</a> 
   for the corresponding HTML documentation that is generated by Doxygen.
   \endhtmlonly
+
+  \par notice: 
+     The \<name\> argument consists of a combination of letters and number
+     digits. If you wish to use upper case letters (e.g. \c MYPAGE1), or 
+     mixed case letters (e.g. \c MyPage1) in the \<name\> argument, you 
+     should set \c CASE_SENSE_NAMES to \c YES. However, this is advisable 
+     only if your file system is case sensitive. Otherwise (and for better 
+     portability) you should use all lower case letters (e.g. \c mypage1) 
+     for \<name\> in all references to the page.
   
   \sa section \ref cmdsection "\\section", section 
               \ref cmdsubsection "\\subsection", and section 
@@ -543,6 +587,23 @@ Doxygen. Unrecognized commands are treated as normal text.
   
   \sa Section \ref cmdjdreturn "@return".
 
+
+<hr>
+\subsection cmdretval \retval <return value> { description }
+
+  \addindex \retval
+  Starts a return value for a function with name 
+  \<return value\>. Followed by a description of the return value. 
+  The text of the paragraph that forms the description has no special
+  internal structure. All visual enhancement commands may be used inside the 
+  paragraph.
+  Multiple adjacent \\retval commands will be joined into a single paragraph.
+  Each return value description will start on a new line.
+  The \\retval description ends when a blank line or some other 
+  sectioning command is encountered. 
+
+  \sa Section \ref cmdjdretval "@retval".
+
 <hr>
 \subsection cmdsa \sa { references }
 
@@ -690,11 +751,17 @@ Doxygen. Unrecognized commands are treated as normal text.
 
   \addindex \dontinclude
   This command can be used to parse a source file without actually 
-  including it. Any class and member declarations inside the code 
+  verbatim including it in the documentation (as the \\include command does). 
+  This is useful if you want to divide the source file into smaller pieces and
+  add documentation between the pieces.
+  Source files or directories can be specified using the \c EXAMPLE_PATH tag 
+  of Doxygen's configuration file.
+
+  The class and member declarations and definitions inside the code fragment
   are `remembered' during the parsing of the comment block that contained 
   the \\dontinclude command. 
 
-  For line by line description of source files, one or more lines 
+  For line by line descriptions of source files, one or more lines 
   of the example can be displayed using the \\line, \\skip, \\skipline, and 
   \\until commands. An internal pointer is used for these commands. The
   \\dontinclude command sets the pointer to the first line of the example.
@@ -717,8 +784,8 @@ Doxygen. Unrecognized commands are treated as normal text.
   \addindex \include
   This command can be used to include a source file as a block of code.
   The command takes the name of an include file as an argument. 
-  Include files or directories can be specified using the 
-  \c INCLUDE_PATH tag of Doxygen's configuration file.
+  Source files or directories can be specified using the 
+  \c EXAMPLE_PATH tag of Doxygen's configuration file.
 
   Using the \\include command is equivalent to inserting the file into 
   the documentation block and surrounding it 
@@ -728,10 +795,9 @@ Doxygen. Unrecognized commands are treated as normal text.
   duplication in case of example blocks that consist of multiple
   source and header files.
 
-  For line by line description of source files, one or more lines 
-  of the example can be displayed using the \\line, \\skip, \\skipline, and 
-  \\until commands. An internal pointer is used for these command. The
-  \\include command sets the pointer to the first line of the example.
+  For a line by line description of a source files use the 
+  \\dontinclude command in combination with the \\line, \\skip, \\skipline, 
+  and \\until commands. 
 
   \sa section \ref cmdexample "\\example" and \ref cmddontinclude "\\dontinclude".
 
@@ -967,6 +1033,45 @@ Doxygen. Unrecognized commands are treated as normal text.
               \ref cmdlatexonly "\\latexonly".
 
 <hr>
+\subsection cmdimage \image <format> <file> [<sizeindication>=<size>]
+
+  \addindex \image
+  Inserts an image into the documentation. This command is format
+  specific, so if you want to insert an image for more than one
+  format you'll have to repeat this command for each format.
+
+  The first argument specifies the output format. Currently, the 
+  following values are supported: \c html and \c latex.
+  
+  The second argument specifies the path and file name of the image. 
+  If a relative path is used, this will be relative to the directory to 
+  which the output of the particular format is written. 
+  For the html format you may also 
+  specify an URL. If the name contains spaces you'll have to put 
+  quotes (") around it.
+  
+  The third argument can be used to specify the width or height of the
+  image. This is only useful for \f$\mbox{\LaTeX}\f$ output
+  (i.e. format=latex). \c sizeindication can be either
+  \c width or \c height. The size should be a valid 
+  size specifier in \f$\mbox{\LaTeX}\f$ (for example <code>10cm</code> or 
+  <code>6in</code>).
+
+\verbatim
+  /*! Here is a snapshot of my new application:
+   *  \image html ../images/application.jpg
+   *  \image latex ../images/application.eps width=10cm
+   */
+\endverbatim
+
+  \warning The image format for HTML is limited to what your
+           browser supports. For \f$\mbox{\LaTeX}\f$ the image format
+           must be an encapsulated postscipt (eps).
+           <br><br>
+           Doxygen does not check if an image exists or if it is in
+           the correct format. So \e you have to make sure this is the case!
+
+<hr>
 \subsection cmdlatexonly \latexonly
 
   \addindex \latexonly
@@ -1078,6 +1183,9 @@ The following command JavaDoc command are support.
 \subsection cmdjdreturn @return { description of the return value }
   \addindex @return
   Equivalent to \\return (see section \ref cmdreturn "\\return").
+\subsection cmdjdretval @retval <return value name> { return value description }
+  \addindex @retval
+  Equivalent to \\retval (see section \ref cmdretval "\\retval").
 \subsection cmdjdsee @see { references }
   \addindex @see
   Equivalent to \\sa (see section \ref cmdsa "\\sa").