diff options
Diffstat (limited to 'doc/docblocks.doc')
| -rw-r--r-- | doc/docblocks.doc | 396 |
1 files changed, 0 insertions, 396 deletions
diff --git a/doc/docblocks.doc b/doc/docblocks.doc deleted file mode 100644 index a0132d8..0000000 --- a/doc/docblocks.doc +++ /dev/null @@ -1,396 +0,0 @@ -/****************************************************************************** - * - * - * - * Copyright (C) 1997-2005 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 code there is -a different comment convention, which can be found in section -\ref pythonblocks - -For each code item there are two types of descriptions, which together -form the documentation: a \e brief description and \e detailed -description, both are optional. -Having more than one brief or detailed description however, is -not allowed. - -As the name suggest, a brief description is -a short one-liner, whereas the detailed description provides longer, -more detailed documentation. - -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 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 - -<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 - -</ol> - -For the brief description there are also several posibilities: -<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 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. - -</ol> - -As you can see doxygen is quite flexible. The following however is -not legal - -\verbatim -//! Brief description, which is -//! really a detailed description since it spans multiple lines. -/*! Oops, another detailed description! - */ -\endverbatim - -because doxygen only allows one brief and one detailed description. - -Furthermore, if there is one brief description before a declaration -and one before a definition of a code item, only the one before -the \e declaration will be used. If the same situation occurs for a -detailed description, the one before the \e definition is preferred -and the one before the declaration will be ignored. - -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 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 <a href="$(DOXYGEN_DOCDIR)/examples/jdstyle/html/class_test.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - -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 should put an additional \< marker -in the comment block. - -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 - -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 ignored inside these comment blocks. - -\section structuralcommands Documentation at other places - -So far we have assumed that the documentation blocks are 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 before (or after) an item is the need to put a -structural command inside the documentation block, which leads to some -duplication of information. - -Structural commands (like 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. - -\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 <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 support 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 "OPTMIZE_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 - -*/ |