diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/docblocks.doc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Orb/Doxygen/doc/docblocks.doc Thu Jan 21 17:29:01 2010 +0000 @@ -0,0 +1,451 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2008 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 + +\section specialblock Special documentation blocks + +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 and VHDL +code there are a different comment conventions, which can be found in section +\ref pythonblocks and \ref vhdlblocks respectively. + +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 +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 +use to provide tooltips at places where an item is referenced. + +There are several ways to mark a comment block as a detailed description: +
    +
  1. You can use the JavaDoc style, which consist of a C-style comment +block starting with two *'s, like this: + +\verbatim +/** + * ... text ... + */ +\endverbatim + +
  2. 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. + +
  3. A third alternative is to use a block of at least two 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. + +
  4. + +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 + +
+ +For the brief description there are also several posibilities: +
    +
  1. 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 + +
  2. 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 + +
  3. 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 descripion. + +//! 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. + +
+ +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. + +Here is an example of a documented piece of C++ code using the Qt style: +\include qtstyle.cpp + \htmlonly + Click here + 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 behaviour 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 here + 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 +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. + +\section 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 +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 \@param to document the parameters +and then use [in], [out], [in,out] +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 here + 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 \\class) are not allowed + inside these comment blocks. + +\section 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. +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 all other commands) start with a backslash +(\\), or an at-sign (\@) 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: + +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 +must document the file in which they are defined. In other words, +there must 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 here + 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. + +\section pythonblocks Special documentation 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 here + 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 here + 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 "OPTMIZE_OUTPUT_JAVA" to \c YES in the +config file. + + +\htmlonly +Go to the next section or return to the + index. +\endhtmlonly + +\section vhdlblocks Special documentation 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 multiline +--! 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 here + 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. + +*/