diff options
Diffstat (limited to 'trunk/doc/docblocks.doc')
-rw-r--r-- | trunk/doc/docblocks.doc | 600 |
1 files changed, 0 insertions, 600 deletions
diff --git a/trunk/doc/docblocks.doc b/trunk/doc/docblocks.doc deleted file mode 100644 index facd1b5..0000000 --- a/trunk/doc/docblocks.doc +++ /dev/null @@ -1,600 +0,0 @@ -/****************************************************************************** - * - * - * - * Copyright (C) 1997-2012 by Dimitri van Heesch. - * - * Permission to use, copy, modify, and distribute this software and its - * documentation under the terms of the GNU General Public License is hereby - * granted. No representations are made about the suitability of this software - * for any purpose. It is provided "as is" without express or implied warranty. - * See the GNU General Public License for more details. - * - * Documents produced by Doxygen are derivative works derived from the - * input used in their production; they are not affected by this license. - * - */ -/*! \page docblocks Documenting the code -\tableofcontents - -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. - -\section specialblock Special comment blocks - -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 -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, -as the order in which the descriptions will appear is not specified). - -As the name suggest, a brief description is -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 -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> -<li> You can use the JavaDoc style, which consist of a C-style comment -block starting with two *'s, like this: - -\verbatim -/** - * ... text ... - */ -\endverbatim - -<li> or you can use the Qt style and add an exclamation mark (!) -after the opening of a C-style comment block, as shown in this example: - -\verbatim -/*! - * ... text ... - */ -\endverbatim - -In both cases the intermediate *'s are optional, so - -\verbatim -/*! - ... text ... -*/ -\endverbatim - -is also valid. - -<li> A third alternative is to use a block of <i>at least two</i> C++ comment -lines, where each line starts with an additional slash or an -exclamation mark. Here are examples of the two cases: - -\verbatim -/// -/// ... text ... -/// -\endverbatim - -or - -\verbatim -//! -//!... text ... -//! -\endverbatim - -Note that a blank line ends a documentation block in this case. - -<li> - -Some people like to make their comment blocks more visible in the -documentation. For this purpose you can use the following: - -\verbatim -/********************************************//** - * ... text - ***********************************************/ -\endverbatim -(note the 2 slashes to end the normal comment block and start a special comment block). - -or - -\verbatim -///////////////////////////////////////////////// -/// ... text ... -///////////////////////////////////////////////// -\endverbatim - -</ol> - -For the brief description there are also several possibilities: -<ol> -<li>One could use the \ref cmdbrief "\\brief" command with one of the -above comment blocks. This command ends at the end of a paragraph, -so the detailed description follows after an empty line. - -Here is an example: - -\verbatim -/*! \brief Brief description. - * Brief description continued. - * - * Detailed description starts here. - */ -\endverbatim - -<li>If \ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" is set to \c YES - in the configuration file, - then using JavaDoc style comment - blocks will automatically start a brief description which ends at the - first dot followed by a space or new line. Here is an example: - -\verbatim -/** Brief description which ends at this dot. Details follow - * here. - */ -\endverbatim -The option has the same effect for multi-line special C++ comments: -\verbatim -/// Brief description which ends at this dot. Details follow -/// here. -\endverbatim - -<li>A third option is to use a special C++ style comment which does not - span more than one line. Here are two examples: -\verbatim -/// Brief description. -/** Detailed description. */ -\endverbatim - -or - -\verbatim -//! Brief description. - -//! Detailed description -//! starts here. -\endverbatim - -Note the blank line in the last example, which is required to separate the -brief description from the block containing the detailed description. The -\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" should also be set to \c NO -for this case. - -</ol> - -As you can see doxygen is quite flexible. If you have multiple -detailed descriptions, like in the following example: - -\verbatim -//! Brief description, which is -//! really a detailed description since it spans multiple lines. -/*! Another detailed description! - */ -\endverbatim - -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. - - -Unlike most other documentation systems, doxygen also allows you to put -the documentation of members (including global functions) in front of -the \e definition. This way the documentation can be placed in the source -file instead of the header file. This keeps the header file compact, and allows the -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. - -\subsubsection memberdoc Putting documentation after members - -If you want to document the members of a file, struct, union, class, or enum, -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 -of a function. - -Here are some examples: -\verbatim -int var; /*!< Detailed description after the member */ -\endverbatim -This block can be used to put a Qt style detailed -documentation block \e after a member. Other ways to do the -same are: -\verbatim -int var; /**< Detailed description after the member */ -\endverbatim -or -\verbatim -int var; //!< Detailed description after the member - //!< -\endverbatim -or -\verbatim -int var; ///< Detailed description after the member - ///< -\endverbatim - -Most often one only wants to put a brief description after a member. -This is done as follows: -\verbatim -int var; //!< Brief description after the member -\endverbatim -or -\verbatim -int var; ///< Brief description after the member -\endverbatim - -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. -\verbatim -void foo(int v /**< [in] docs for input parameter v. */); -\endverbatim - -Note that these blocks have the same structure and meaning as the -special comment blocks in the previous section -only the \< indicates that the member is -located in front of the block instead of after the block. - -Here is an example of the use of these comment blocks: -\include afterdoc.h - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/afterdoc/html/class_test.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - -\warning These blocks can only be used to document \e members and \e parameters. - They cannot be used to document files, classes, unions, structs, - groups, namespaces and enums themselves. Furthermore, the structural - commands mentioned in the next section - (like <code>\\class</code>) are not allowed - inside these comment blocks. - -\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 - -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". - -Doxygen allows you to put your documentation blocks practically -anywhere (the exception is inside the body of a function or inside a -normal C style comment block). - -The price you pay for not putting the -documentation block directly before (or after) an item is the need to put a -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 \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 -above, you could have also put the following documentation block somewhere -in the input that is read by doxygen: -\verbatim -/*! \class Test - \brief A test class. - - A more detailed class description. -*/ -\endverbatim - -Here the special command \c \\class is used to indicate that the -comment block contains documentation for the class \c Test. -Other structural commands are: -<ul> -<li>\c \\struct to document a C-struct. -<li>\c \\union to document a union. -<li>\c \\enum to document an enumeration type. -<li>\c \\fn to document a function. -<li>\c \\var to document a variable or typedef or enum value. -<li>\c \\def to document a \#define. -<li>\c \\typedef to document a type definition. -<li>\c \\file to document a file. -<li>\c \\namespace to document a namespace. -<li>\c \\package to document a Java package. -<li>\c \\interface to document an IDL interface. -</ul> -See section \ref commands for detailed information about these and many other -commands. - -To document a member of a C++ class, you must also document the class -itself. The same holds for namespaces. To document a global C function, -typedef, enum or preprocessor definition you must first document the file -that contains it (usually this will be a header file, because that file -contains the information that is exported to other source files). - -Let's repeat that, because it is often overlooked: -to document global objects (functions, typedefs, enum, macros, etc), you -<em>must</em> document the file in which they are defined. In other words, -there <em>must</em> at least be a \verbatim /*! \file */ \endverbatim -or a \verbatim /** @file */ \endverbatim line in this file. - -Here is an example of a C header named \c structcmd.h that is documented -using structural commands: -\include structcmd.h - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/structcmd/html/structcmd_8h.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - - Because each comment block in the example above contains a structural command, all - the comment blocks could be moved to another location or input file - (the source file for instance), without affecting the generated - documentation. The disadvantage of this approach is that prototypes are - duplicated, so all changes have to be made twice! Because of this you - should first consider if this is really needed, and avoid structural - commands if possible. I often receive examples that contain \\fn command - 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. - -\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__ -and can be retrieved at runtime. Doxygen will extract such comments -and assume they have to be represented in a preformatted way. - -\include docstring.py - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/docstring/html/index.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - -Note that in this case none of doxygen's \ref cmd_intro "special commands" -are supported. - -There is also another way to document Python code using comments that -start with "##". These type of comment blocks are more in line with the -way documentation blocks work for the other languages supported by doxygen -and this also allows the use of special commands. - -Here is the same example again but now using doxygen style comments: - -\include pyexample.py - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/pyexample/html/index.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - -Since python looks more like Java than like C or C++, you should set -\ref cfg_optimize_output_java "OPTIMIZE_OUTPUT_JAVA" to \c YES in the -config file. - - -\htmlonly -Go to the <a href="lists.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -\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; -a one line --! comment representing a brief description, and a multi-line ---! comment (where the --! prefix is repeated for each line) representing -a detailed description. - -Comments are always located in front of the item that is being documented -with one exception: for ports the comment can also be after the item -and is then treated as a brief description for the port. - -Here is an example VHDL file with doxygen comments: - -\include mux.vhdl - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/mux/html/index.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - -To get proper looking output you need to set -\ref cfg_optimize_output_vhdl "OPTIMIZE_OUTPUT_VHDL" to \c YES in the -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. - -\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. - -For Fortran "!>" or "!<" starts a comment and "!!" or "!>" can be used to -continuate a one line comment into a multi-line comment. - -Here is an example of a documented Fortran subroutine: -\verbatim - !> Build the restriction matrix for the aggregation - !! method. - !! @param aggr information about the aggregates - !! @todo Handle special case - subroutine IntRestBuild(A,aggr,Restrict,A_ghost) - implicit none - Type(SpMtx), intent(in) :: A !< our fine level matrix - Type(Aggrs), intent(in) :: aggr - Type(SpMtx), intent(out) :: Restrict !< Our restriction matrix -\endverbatim - -As a alternative you can also use comments in fixed format code: - -\verbatim -C> Function comment -C> another line of comment - function A(i) -C> input parameter - integer i - end function A -\endverbatim - -\subsection tclblocks Comment blocks in Tcl - -Doxygen documentation can be included in normal Tcl comments. - -To start a new documentation block start a line with \c ## (two hashes). -All following comment lines and continuation lines will be added to this -block. The block ends with a line not starting with a \c # (hash sign). - -A brief documentation can be added with \c ;#< (semicolon, hash and -lower then sign). The brief documentation also ends at a line not starting -with a \c # (hash sign). - -Inside doxygen comment blocks all normal doxygen markings are supported. -The only exceptions are described in the following two paragraphs. - -If a doxygen comment block ends with a line containing only -\c #\\code or \c #\@code all code until a line only containing \c #\\endcode -or \c #\@endcode is added to the generated documentation as code block. - -If a doxygen comment block ends with a line containing only -\c #\\verbatim or \c #\@verbatim all code until a line only containing -\c #\\endverbatim or \c #\@endverbatim is added verbatim to the generated -documentation. - -To detect namespaces, classes, functions and variables the following -Tcl commands are recognized. Documentation blocks can be put on the lines -before the command. - -<ul> -<li><tt>namespace eval ..</tt> Namespace -<li><tt>proc ..</tt> Function -<li><tt>variable ..</tt> Variable -<li><tt>common ..</tt> Common variable -<li><tt>itcl::class ..</tt> Class -<li><tt>itcl::body ..</tt> Class method body definition -<li><tt>oo::class create ..</tt> Class -<li><tt>oo::define ..</tt> OO Class definition -<li><tt>method ..</tt> Class method definitions -<li><tt>constructor ..</tt> Class constructor -<li><tt>destructor ..</tt> Class destructor -<li><tt>public ..</tt> Set protection level -<li><tt>protected ..</tt> Set protection level -<li><tt>private ..</tt> Set protection level -</ul> - -<!-- -To use your own keywords you an map these keyword to the recognized commands -using the \ref cfg_tcl_subs "TCL_SUBST" entry in the config file. -The entry contain a list of word-keyword mappings. To use the itcl::* -commands without the leading namespace use p.e.: - -\verbatim TCL_SUBST = class itcl:class body itcl:body \endverbatim ---> - -Following is a example using doxygen style comments: - -\include tclexample.tcl - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/tclexample/html/index.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - -\htmlonly -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 focused 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. - -*/ |