Release-1.7.6.1-20120122

1 files changed, 114 insertions, 66 deletions

diff --git a/doc/docblocks.doc b/doc/docblocks.doc
index bf0466a..093122b 100644
--- a/doc/docblocks.doc
+++ b/doc/docblocks.doc
@@ -16,19 +16,30 @@
  */
 /*! \page docblocks Documenting the code
 
-\section specialblock Special documentation blocks
+This chapter covers two topics:
+1. How to put comments in your code such that doxygen incorporates them in
+   the documentation it generates. 
+   This is further detailed in the \ref specialblock "next section".
+2. Ways to structure the contents of a comment block such that the output
+   looks good, as explained in section \ref docstructure.
 
-A special documentation block is a C or C++ style comment block with some 
-additional markings, so doxygen knows it is a piece of documentation that
-needs to end up in the generated documentation. For Python, VHDL, Fortran, and
-Tcl code there are different comment conventions, which can be found in sections
-\ref pythonblocks, \ref vhdlblocks, \ref fortranblocks, and \ref tclblocks 
-respectively.
+\section specialblock Special comment blocks 
 
-For each code item there are two (or in some cases three) types of descriptions, 
-which together form the documentation: a \e brief description and \e detailed
+A special comment block is a C or C++ style comment block with some 
+additional markings, so doxygen knows it is a piece of structured text that
+needs to end up in the generated documentation. The \ref cppblock "next" section
+presents the various styles supported by doxygen.
+
+For Python, VHDL, Fortran, and Tcl code there are different commenting 
+conventions, which can be found in sections \ref pythonblocks, \ref vhdlblocks, 
+\ref fortranblocks, and \ref tclblocks respectively.
+
+\subsection cppblock Comment blocks for C-like languages (C/C++/C#/Objective-C/PHP/Java)
+
+For each entity in the code there are two (or in some cases three) types of descriptions, 
+which together form the documentation for that entity; a *brief* description and *detailed*
 description, both are optional. For methods and functions there is also a third
-type of description, the so called "in body" description, which consists of 
+type of description, the so called *in body* description, which consists of 
 the concatenation of all comment blocks found within the body of the method or function.
 
 Having more than one brief or detailed description is allowed (but not recommended,
@@ -39,7 +50,7 @@ a short one-liner, whereas the detailed description provides longer,
 more detailed documentation. An "in body" description can also act as a detailed
 description or can describe a collection of implementation details.
 For the HTML output brief descriptions are also
-use to provide tooltips at places where an item is referenced.
+used to provide tooltips at places where an item is referenced.
 
 There are several ways to mark a comment block as a detailed description:
 <ol>
@@ -183,49 +194,6 @@ They will be joined. Note that this is also the case if the descriptions
 are at different places in the code! In this case the order will depend
 on the order in which doxygen parses the code.
 
-Here is an example of a documented piece of C++ code using the Qt style:
-\include qtstyle.cpp
- \htmlonly
- Click <a href="$(DOXYGEN_DOCDIR)/examples/qtstyle/html/class_test.html">here</a>
- for the corresponding HTML documentation that is generated by doxygen.
- \endhtmlonly
-
-The one-line comments contain a brief description, 
-whereas the multi-line comment blocks contain a more detailed description.
-
-The brief descriptions are included in the member overview of a 
-class, namespace or file and are printed using a small italic font 
-(this description can be hidden by setting 
-\ref cfg_brief_member_desc "BRIEF_MEMBER_DESC" to \c NO in 
-the config file). By default the brief descriptions become the first 
-sentence of the detailed descriptions 
-(but this can be changed by setting the \ref cfg_repeat_brief "REPEAT_BRIEF" 
-tag to \c NO). Both the brief and the detailed descriptions are optional 
-for the Qt style. 
-
-By default a JavaDoc style documentation block behaves the same way as a
-Qt style documentation block. This is not according the JavaDoc specification
-however, where the first sentence of the documentation block is automatically
-treated as a brief description. To enable this behavior you should set
-\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to YES in the configuration
-file. If you enable this option and want to put a dot in the middle of a
-sentence without ending it, you should put a backslash and a space after it.
-Here is an example:
-\verbatim
-  /** Brief description (e.g.\ using only a few words). Details follow. */
-\endverbatim
-
-Here is the same piece of code as shown above, this time documented using the 
-JavaDoc style and \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" set to YES:
-\include jdstyle.cpp
- \htmlonly
- Click <a href="$(DOXYGEN_DOCDIR)/examples/jdstyle/html/class_test.html">here</a>
- for the corresponding HTML documentation that is generated by doxygen.
- \endhtmlonly
-
-Similarly, if one wishes the first sentence of a Qt style documentation
-block to automatically be treated as a brief description, one may set
-\ref cfg_qt_autobrief "QT_AUTOBRIEF" to YES in the configuration file.
 
 Unlike most other documentation systems, doxygen also allows you to put
 the documentation of members (including global functions) in front of 
@@ -235,10 +203,9 @@ implementer of the members more direct access to the documentation.
 As a compromise the brief description could be placed before the
 declaration and the detailed description before the member definition.
 
-\section memberdoc Putting documentation after members 
+\subsubsection memberdoc Putting documentation after members 
 
 If you want to document the members of a file, struct, union, class, or enum,
-and you want to put the documentation for these members inside the compound,
 it is sometimes desired to place the documentation block after the member 
 instead of before. For this purpose you have to put an additional \< marker
 in the comment block. Note that this also works for the parameters 
@@ -275,7 +242,7 @@ or
 int var; ///< Brief description after the member
 \endverbatim
 
-For functions one can use \@param to document the parameters
+For functions one can use the \ref cmdparam "\@param" command to document the parameters
 and then use <code>[in]</code>, <code>[out]</code>, <code>[in,out]</code> 
 to document the direction. For inline documentation this is also possible 
 by starting with the direction attribute, e.g.
@@ -302,11 +269,54 @@ Here is an example of the use of these comment blocks:
          (like <code>\\class</code>) are not allowed 
          inside these comment blocks.
 
-\section structuralcommands Documentation at other places
+\subsubsection docexamples Examples
+
+Here is an example of a documented piece of C++ code using the Qt style:
+\include qtstyle.cpp
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/qtstyle/html/class_test.html">here</a>
+ for the corresponding HTML documentation that is generated by doxygen.
+ \endhtmlonly
+
+The brief descriptions are included in the member overview of a 
+class, namespace or file and are printed using a small italic font 
+(this description can be hidden by setting 
+\ref cfg_brief_member_desc "BRIEF_MEMBER_DESC" to \c NO in 
+the config file). By default the brief descriptions become the first 
+sentence of the detailed descriptions 
+(but this can be changed by setting the \ref cfg_repeat_brief "REPEAT_BRIEF" 
+tag to \c NO). Both the brief and the detailed descriptions are optional 
+for the Qt style. 
+
+By default a JavaDoc style documentation block behaves the same way as a
+Qt style documentation block. This is not according the JavaDoc specification
+however, where the first sentence of the documentation block is automatically
+treated as a brief description. To enable this behavior you should set
+\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to YES in the configuration
+file. If you enable this option and want to put a dot in the middle of a
+sentence without ending it, you should put a backslash and a space after it.
+Here is an example:
+\verbatim
+  /** Brief description (e.g.\ using only a few words). Details follow. */
+\endverbatim
+
+Here is the same piece of code as shown above, this time documented using the 
+JavaDoc style and \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" set to YES:
+\include jdstyle.cpp
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/jdstyle/html/class_test.html">here</a>
+ for the corresponding HTML documentation that is generated by doxygen.
+ \endhtmlonly
+
+Similarly, if one wishes the first sentence of a Qt style documentation
+block to automatically be treated as a brief description, one may set
+\ref cfg_qt_autobrief "QT_AUTOBRIEF" to YES in the configuration file.
+
+\subsubsection structuralcommands Documentation at other places
 
-So far we have assumed that the documentation blocks are always located \e in 
-\e front of the declaration or definition of a file, class or namespace or in
-front or after one of its members. 
+In the examples in the previous section the comment blocks were always located *in 
+front* of the declaration or definition of a file, class or namespace or *in
+front* or *after* one of its members. 
 Although this is often comfortable, there may sometimes be reasons to put the 
 documentation somewhere else. For documenting a file this is even 
 required since there is no such thing as "in front of a file". 
@@ -321,7 +331,7 @@ structural command inside the documentation block, which leads to some
 duplication of information. So in practice you should \e avoid the use of
 structural commands \e unless other requirements force you to do so.
 
-Structural commands (like all other commands) start with a backslash 
+Structural commands (like \ref cmd_intro "all other commands") start with a backslash 
 (<tt>\\</tt>), or an at-sign (<tt>\@</tt>) if you prefer JavaDoc style, 
 followed by a command name and one or more parameters.
 For instance, if you want to document the class \c Test in the example
@@ -384,7 +394,7 @@ using structural commands:
  in comment blocks which are place in front of a function. This is clearly
  a case where the \\fn command is redundant and will only lead to problems.
 
-\section pythonblocks Special documentation blocks in Python
+\subsection pythonblocks Comment blocks in Python
 
 For Python there is a standard way of documenting the code using 
 so called documentation strings. Such strings are stored in \c __doc__
@@ -423,7 +433,7 @@ Go to the <a href="lists.html">next</a> section or return to the
  <a href="index.html">index</a>.
 \endhtmlonly
 
-\section vhdlblocks Special documentation blocks in VHDL
+\subsection vhdlblocks Comment blocks in VHDL
 
 For VHDL a comment normally start with "--". Doxygen will extract comments
 starting with "--!". There are only two types of comment blocks in VHDL;
@@ -449,7 +459,7 @@ config file. This will also affect a number of other settings. When they
 were not already set correctly doxygen will produce a warning telling which
 settings where overruled.
 
-\section fortranblocks Special documentation blocks in Fortran
+\subsection fortranblocks Comment blocks in Fortran
 
 When using doxygen for Fortran code you should
 set \ref cfg_optimize_for_fortran "OPTIMIZE_FOR_FORTRAN" to \c YES.
@@ -481,7 +491,7 @@ C> input parameter
       end function A
 \endverbatim
 
-\section tclblocks Documentation blocks in Tcl
+\subsection tclblocks Comment blocks in Tcl
 
 Doxygen documentation can be included in normal Tcl comments.
 
@@ -548,4 +558,42 @@ Go to the <a href="lists.html">next</a> section or return to the
  <a href="index.html">index</a>.
 \endhtmlonly
 
+\section docstructure Anatomy of a comment block
+
+The previous section focussed on how to make the comments in your code known
+to doxygen, it explained the difference between a brief and a detailed description, and
+the use of structural commands.
+
+In this section we look at the contents of the comment block itself.
+
+Doxygen supports various styles of formatting your comments.
+
+The simplest form is to use plain text. This will appear as-is in the output 
+and is ideal for a short description.
+
+For longer descriptions you often will find the 
+need for some more structure, like a block of verbatim text, a list, or a 
+simple table. For this doxygen supports the 
+<a href="http://daringfireball.net/projects/markdown/syntax">Markdown</a> 
+syntax, including parts of the
+<a href="http://michelf.com/projects/php-markdown/extra/">Markdown Extra</a>
+extension. 
+
+Markdown is designed to be very easy to read and write. 
+It's formatting is inspired by plain text mail.
+Markdown works great for simple, generic formatting, like an introduction
+page for your project. Doxygen also supports reading of markdown files 
+directly. See \ref markdown "here" for more details regards Markdown support.
+
+For programming language specific formatting doxygen has two
+forms of additional markup on top of Markdown formatting.
+
+1. <a href="http://en.wikipedia.org/wiki/Javadoc">Javadoc</a> like markup.
+   See \ref cmd_intro "here" for a complete overview of all commands supported by doxygen.
+2. <a href="http://en.wikipedia.org/wiki/C_Sharp_(programming_language)#XML_documentation_system">XML</a> markup
+   as specified in the C# standard. See \ref xmlcmds "here" for the XML commands supported by doxygen.
+
+If this is still not enough doxygen also supports a \ref htmlcmds "subset" of 
+the <a href="http://en.wikipedia.org/wiki/HTML">HTML</a> markup language.
+
 */