diff options
Diffstat (limited to 'doc/docblocks.doc')
| -rw-r--r-- | doc/docblocks.doc | 605 |
1 files changed, 605 insertions, 0 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc new file mode 100644 index 0000000..d6bb675 --- /dev/null +++ b/doc/docblocks.doc @@ -0,0 +1,605 @@ +/****************************************************************************** + * + * + * + * 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. + +\htmlonly +Go to the <a href="markdown.html">next</a> section or return to the + <a href="index.html">index</a>. +\endhtmlonly + +*/ |