diff options
Diffstat (limited to 'doc/starting.doc')
| -rw-r--r-- | doc/starting.doc | 656 |
1 files changed, 1 insertions, 655 deletions
diff --git a/doc/starting.doc b/doc/starting.doc index aad8dc0..332d1d2 100644 --- a/doc/starting.doc +++ b/doc/starting.doc @@ -192,7 +192,7 @@ During parsing the following steps take place: See section \ref htmlcmds for an overview of all supported HTML tags. </ul> -Using a number of column aligned minus signs at the start of a +Using a number of column-aligned minus signs at the start of a line in a comment block will generate a bullet list. Nested lists are also possible. Here is an example: @@ -235,658 +235,4 @@ Go to the <a href="docblocks.html">next</a> section or return to the */ -/*! \page docblocks Documenting the code -\subsection specialblock Special documentation blocks - -The following types of special documentation blocks are supported by doxygen: -<ul> -<li>The Qt style, where special documentation blocks look like: -\verbatim -/*! - ... text ... -*/ -\endverbatim and the one line version: -\verbatim -//! ... one line of text ... -\endverbatim -<li>The JavaDoc style, where special documentation blocks look like: -\verbatim -/** - * ... text ... - */ -\endverbatim and the one line version: -\verbatim -/// ... one line of text ... -\endverbatim -</ul> - -Doxygen only allows one brief and one detailed description. If there is -one brief description before a declaration and one before a -definition, only the one before the \e declaration will be used. If -the same situation occurs for a detail 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: -\verbinclude 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 should 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 are also the first -sentence of the detailed description -(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. - -Here is the same piece of code, this time documented using the JavaDoc -style: -\verbinclude 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 - -Note that by default the first sentence of the documentation (until the <tt>.</tt>) -is treated as a brief description, whereas the documentation block as a whole -forms the detailed description. If you want to put a dot in the middle of a -sentence you should put a backslash and space behind it. Example: -\verbatim - /** Brief description (e.g.\ using only a few words). Details follow. */ -\endverbatim -The brief description is required for the JavaDoc style, unless you set -\ref cfg_javadoc_autobrief "JAVADOC_AUTOBRIEF" to NO. If you do this, -doxygen treats JavaDoc comments just like Qt comments (i.e. You have -to insert an explicit \ref cmdbrief "\\brief" command to add a brief description). - -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 -(assuming you use the Qt style comments). - -\par Note: -Each entity can only have \e one brief and \e one detailed description. If you -specify more than one comment block of the same type, only one will be used, -and all others are ignored! - -\subsection structuralcommands Structural commands - -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 of one of its members. -Although this is often comfortable, it may sometimes be better to put the -documentation somewhere else. For some types of documentation blocks (like file -documentation) this is even required. 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), as long as you put a -structural command inside the documentation block. - -Structural commands (like all other commands) start with a backslash -(<tt>\\</tt>) 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 indicated 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 \file to document a file. -<li>\c \namespace to document a namespace. -</ul> -See section \ref commands for detailed information about these and other -commands. Note that the documentation block belonging to a file -should always contain a structural command. - -To document a member of a C++ class, you must also document the class -itself. The same holds for namespaces. To document a 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). - -Here is an example of a C header named \c structcmd.h that is documented -using structural commands: -\verbinclude structcmd.h - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/structcmd/html/structcmd.h.html">here</a> - for the corresponding HTML documentation that is generated by doxygen. - \endhtmlonly - -\par Note: - 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! - -\subsection memberdoc Documenting compound 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 doxygen has the following -additional comment blocks: -\verbatim -/*!< ... */ -\endverbatim -This block can be used to put a qt style documentation blocks after a member. -The one line version look as follows: -\verbatim -//!< ... -\endverbatim -There are also JavaDoc versions: -\verbatim -/**< ... */ -\endverbatim -and -\verbatim -///< ... -\endverbatim -Note that these blocks have the same structure and meaning as the -special comment blocks above only the \< indicates that the member is -located in front of the block instead of after the block. - -Here is an example of a the use of these comment blocks: -\verbinclude 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. - They cannot be used to document files, classes, unions, structs, - groups, namespaces and enums. Furthermore, the structural commands - mentioned in the previous section (like <code>\\class</code>) are ignored - inside these comment blocks. - -\htmlonly -Go to the <a href="grouping.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -*/ -/*! \page grouping Grouping - -Doxygen has two mechanisms to group things together. -One mechanism works at a global level, creating a new page -for each group. These groups are called "modules" in the documentation. -The other mechanism works within a member list of some compound entity, -and is refered to as a "member group". - -\subsection modules Modules - -Modules are a way to group things together on a separate page. You -can document a group as a whole, as well as all individual members. -Members of a group can be files, namespaces, classes, functions, -variables, enums, typedefs, and defines, but also other groups. - -To define a group, you should put the \ref cmddefgroup "\\defgroup" -command in a special comment block. The first argument of the command -is a label that should uniquely identify the group. You can make an -entity a member of a specific group by putting -a \ref cmdingroup "\\ingroup" command inside its documentation. - -\par Example: -\verbinclude group.cpp - -\htmlonly -Click <a href="$(DOXYGEN_DOCDIR)/examples/group/html/modules.html">here</a> -for the corresponding HTML documentation that is generated by Doxygen. -\endhtmlonly - -\subsection memgroup Member Groups - -If a compound (e.g. a class or file) has many members, it is often -desired to group them together. Doxygen already automatically groups -things together on type and protection level, but maybe you feel that -this is not enough or that that default grouping is wrong. -For instance, because you feel that members of different (syntactic) -types belong to the same (semantic) group. - -A member group is defined by -a -\verbatim -//@{ - ... -//@} -\endverbatim -block or a -\verbatim -/*@{*/ - ... -/*@}*/ -\endverbatim -block if you prefer C style -comments. Note that the members of the group should be -physcially inside the member group's body. - -Before the opening marker of a block a separate comment block may be -placed. This block should contain the \ref cmdname "@name" -(or \ref cmdname "\name") command and is used to specify the header -of the group. Optionally, the comment block may also contain more -detailed information about the group. - -Nesting of member groups is not allowed. - -If all members of a member group inside a class have the same type -and protection level (for instance all are static public members), -then the whole member group is displayed as a subgroup of -the type/protection level group (the group is displayed as a -subsection of the "Static Public Members" section for instance). -If two or more members have different types, then the group is put -at the same level as the automatically generated groups. -If you want to force all member-groups of a class to be at the top level, -you should put a \ref cmdnosubgrouping "\\nosubgrouping" command inside the -documentation of the class. - -\par Example: -\verbinclude memgrp.cpp - -\htmlonly -Click <a href="$(DOXYGEN_DOCDIR)/examples/memgrp/html/class_test.html">here</a> -for the corresponding HTML documentation that is generated by Doxygen. -\endhtmlonly - -Here Group1 is displayed as a subsection of the "Public Members". And -Group2 is a separate section because it contains members with -different protection levels (i.e. public and protected). - -\htmlonly -Go to the <a href="formulas.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -*/ -/*! \page formulas Including formulas - -Doxygen allows you to put \f$\mbox{\LaTeX}\f$ formulas in the -output (this works only for the HTML and \f$\mbox{\LaTeX}\f$ formats, -not for the man page output). To be able to include formulas (as images) -in the HTML documentation, you will also need to have the following tools -installed -<ul> -<li>\c latex: the \f$\mbox{\LaTeX}\f$ compiler, needed to parse the formulas. - To test I have used the teTeX 0.9 distribution. -<li>\c dvips: a tool to convert dvi files to postscript files - I have used version 5.86 from Radical Eye software for testing. -<li>\c gs: the ghostscript interpreter for converting postscript files - to bitmaps. I have used Aladdin Ghostscript 5.10 for testing. -</ul> - -There are two ways to include formulas in the documentation. -<ol> -<li>Using in-text formulas that appear in the running text. - These formulas should be put between a pair of \\f\$ - commands, so -\verbatim - The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is - \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$. -\endverbatim results in: - - The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is - \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$. -<br> -<li>Unnumbered displayed formulas that are centered on a separate line. - These formulas should be put between \\f\[ and \\f\] commands. - An example: -\verbatim - \f[ - |I_2|=\left| \int_{0}^T \psi(t) - \left\{ - u(a,t)- - \int_{\gamma(t)}^a - \frac{d\theta}{k(\theta,t)} - \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi - \right\} dt - \right| - \f] -\endverbatim - results in: - \f[ - |I_2|=\left| \int_{0}^T \psi(t) - \left\{ - u(a,t)- - \int_{\gamma(t)}^a - \frac{d\theta}{k(\theta,t)} - \int_{a}^\theta c(\xi)u_t(\xi,t)\,d\xi - \right\} dt - \right| - \f] -</ol> -Formulas should be valid commands in \f$\mbox{\LaTeX}\f$'s math-mode. - -\warning Currently, doxygen is not very fault tolerant in recovering -from typos in formulas. It may have to be necessary to remove the -file <code>formula.repository</code> that is written in the html directory to -a rid of an incorrect formula - -\htmlonly -Go to the <a href="diagrams.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -*/ - -/*! \page diagrams Graphs and diagrams - - Doxygen has build-in support to generate inheritance diagrams for C++ - classes. - - Doxygen can use the "dot" tool from graphviz 1.5 to generate - more advanced diagrams & graphs. Graphviz is an open-sourced, - cross-platform graph drawing toolkit from AT&T and Lucent Bell Labs and - can be found at http://www.research.att.com/sw/tools/graphviz/ - - If you have the "dot" tool available in the path, you can set - \ref cfg_have_dot "HAVE_DOT" to \c YES in the configuration file to - let doxygen use it. - - Doxygen uses the "dot" tool to generate the following graphs: - <ul> - <li>if \ref cfg_graphical_hierarchy "GRAPHICAL_HIERARCHY" is set to \c YES, - a graphical representation of the class hierarchy will be drawn, along - with the textual one. Currently this feature is supported for HTML only.\n - <b>Warning:</b> When you have a very large class hierarchy where many - classes derive from a common base class, the resulting image may become - too big to handle for some browsers. - <li>if \ref cfg_class_graph "CLASS_GRAPH" is set to \c YES, - a graph will be generated for each documented class showing the - direct and indirect inheritance relations. This disables the - generation of the build-in class inheritance diagrams. - <li>if \ref cfg_include_graph "INCLUDE_GRAPH" is set to \c YES, an include - dependency graph is generated for each documented file that includes at - least one other file. This feature is currently supported for HTML and RTF - only. - <li>if \ref cfg_collaboration_graph "COLLABORATION_GRAPH" is set to YES, a - graph is drawn for each documented class and struct that shows: - <ul> - <li> the inheritance relations with base classes. - <li> the usage relations with other structs & classes (e.g. - class \c A has a member variable \c m_a of type class \c B, then - \c A has an arrow to \c B with \c m_a as label). - </ul> - </ul> - - The elements in the class diagrams in HTML and RTF - have the following meaning: - <ul> - <li> A \b yellow box indicates a class. A box can have a - little marker in the lower right corner to indicate that the class - contains base classes that are hidden. - For the class diagrams the maximum tree width is currently 8 elements. - If a tree wider some nodes will be hidden. - If the box is filled with a - dashed pattern the inheritance relation is virtual. - <li> A \b white box indicates that the documentation of the class - is currently shown. - <li> A \b grey box indicates an undocumented class. - <li> A <b>solid dark blue</b> arrow indicates public inheritance. - <li> A <b>dashed dark green</b> arrow indicates protected inheritance. - <li> A <b>dotted dark green</b> arrow indicates private inheritance. - </ul> - - The elements in the class diagram in \f$\mbox{\LaTeX}\f$ have the - following meaning: - <ul> - <li> A \b white box indicates a class. - A \b marker in the lower right corner of the box indicates that the - class has base classes that are hidden. - If the box has a \b dashed border this indicates virtual inheritance. - <li> A \b solid arrow indicates public inheritance. - <li> A \b dashed arrow indicates protected inheritance. - <li> A \b dotted arrow indicated private inheritance. - </ul> - - The elements in the graphs generated by the dot tool have the following - meaning: - <ul> - <li> A \b white box indicates a class or struct or file. - <li> A box with a \b red border indicates a node that has - \e more arrows than are shown! - In order words: the graph is \e truncated with respect to this node. - The reason a graph is sometimes truncated is too prevent images - from becoming too large. - For the graphs generated with dot doxygen tries - to limit the width of the resulting image to 1024 pixels. - <li> A \b black box indicates that the class' documentation is currently shown. - <li> A <b>dark blue</b> arrow indicates an include relation (for the - include dependency graph) or public inheritance (for the other graphs). - <li> A <b>dark green</b> arrow indicates protected inheritance. - <li> A <b>dark red</b> arrow indicates private inheritance. - <li> A <b>purple dashed</b> arrow indicated a "usage" relation, the - edge of the arrow is labled with the variable(s) responsible for the - relation. - Class \c A uses class \c B, if class \c A has a member variable \c m - of type C, where B is a subtype of C (e.g. C could be \c B, \c B*, <code>T\<B\>*</code> ). - </ul> - - -Here are a couple of header files that together show the various diagrams -that doxygen can generate: - -<code>diagrams_a.h</code> -\verbinclude diagrams_a.h -<code>diagrams_b.h</code> -\verbinclude diagrams_b.h -<code>diagrams_c.h</code> -\verbinclude diagrams_c.h -<code>diagrams_d.h</code> -\verbinclude diagrams_d.h -<code>diagrams_e.h</code> -\verbinclude diagrams_e.h - - \htmlonly - Click <a href="$(DOXYGEN_DOCDIR)/examples/diagrams/html/index.html">here</a> - for the corresponding HTML documentation that is generated by doxygen<br> - (<code>EXTRACT_ALL</code> = <code>YES</code> is used here). - \endhtmlonly - -\htmlonly -Go to the <a href="preprocessing.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -*/ - -/*! \page preprocessing Preprocessing - -Source files that are used as input to doxygen can be parsed by doxygen's -build-in C-preprocessor. - -By default doxygen does only partial preprocessing. That is, it -evaluates conditional compilation statements (like \#if) and -evaluates macro definitions, but it does not perform macro expansion. - -So if you have the following code fragment -\verbatim -#define VERSION 200 -#define CONST_STRING const char * - -#if VERSION >= 200 - static CONST_STRING version = "2.xx"; -#else - static CONST_STRING version = "1.xx"; -#endif -\endverbatim - -Then by default doxygen will feed the following to its parser: - -\verbatim -#define VERSION -#define CONST_STRING - - static CONST_STRING version = "2.xx"; -\endverbatim - -You can disable all preprocessing by setting -\ref cfg_enable_preprocessing "ENABLE_PREPROCESSING" to \c -NO in the configuation file. In the case above doxygen will then reads -both statements! - -In case you want to expand the \c CONST_STRING macro, you should set the -\ref cfg_macro_expansion "MACRO_EXPANSION" tag in the config file -to \c YES. Then the result after preprocessing becomes: - -\verbatim -#define VERSION -#define CONST_STRING - - static const char * version = "1.xx"; -\endverbatim - -Note that doxygen will now expand \e all macro definitions -(recursively if needed). This is often too much. Therefore, doxygen also -allows you to expand only those defines that you explicitly -specify. For this you have to set the -\ref cfg_expand_only_predef "EXPAND_ONLY_PREDEF" tag to \c YES -and specify the macro definitions after -the \ref cfg_predefined "PREDEFINED" tag. - -As an example, suppose you have the following obfusciated code fragment -of an abstract base class called \c IUnknown: - -\verbatim -/*! A reference to an IID */ -#ifdef __cplusplus -#define REFIID const IID & -#else -#define REFIID const IID * -#endif - - -/*! The IUnknown interface */ -DECLARE_INTERFACE(IUnknown) -{ - STDMETHOD(HRESULT,QueryInterface) (THIS_ REFIID iid, void **ppv) PURE; - STDMETHOD(ULONG,AddRef) (THIS) PURE; - STDMETHOD(ULONG,Release) (THIS) PURE; -}; -\endverbatim - -without macro expansion doxygen will get confused, but we may not want to -expand the REFIID macro, because it is documented and the user that reads -the documentation should use it when implementing the interface. - -By setting the following in the config file: - -\verbatim -ENABLE_PREPROCESSING = YES -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -PREDEFINED = "DECLARE_INTERFACE(name)=class name" \ - "STDMETHOD(result,name)=virtual result name" \ - "PURE= = 0" \ - THIS_= \ - THIS= \ - __cplusplus -\endverbatim - -we can make sure that the proper result is fed to doxygen's parser: -\verbatim -/*! A reference to an IID */ -#define REFIID - -/*! The IUnknown interface */ -class IUnknown -{ - virtual HRESULT QueryInterface ( REFIID iid, void **ppv) = 0; - virtual ULONG AddRef () = 0; - virtual ULONG Release () = 0; -}; -\endverbatim - -Note that the \ref cfg_predefined "PREDEFINED" tag accepts function -like macro definitions -(like \c DECLARE_INTERFACE ), normal macro -substitutions (like \c PURE and \c THIS) and plain -defines (like \c __cplusplus). - -Note also that preprocessor definitions that are normally defined -automatically by the preprocessor (like \c __cplusplus), have to be defined -by hand with doxygen's parser (this is done because these defines -are often platform/compiler specific). - -In some cases you may want to substitute a macro name or function by -something else without exposing the result to further macro substitution. -You can do this but using the <code>:=</code> operator instead of -<code>=</code> - -As an example suppose we have the following piece of code: -\verbatim -#define QList QListT -class QListT -{ -}; -\endverbatim - -Then the only way to get doxygen interpret this as a class definition -for class QList is to define: -\verbatim -PREDEFINED = QListT:=QList -\endverbatim - -Here is example provided by Valter Minute that helps doxygen to -wade through the boilerplate code in Microsoft's ATL library: - -\verbatim -PREDEFINED = DECLARE_REGISTRY_RESOURCEID=// \ - DECLARE_PROTECT_FINAL_CONSTRUCT=// \ - BEGIN_COM_MAP=/* \ - END_COM_MAP=*/// \ - BEGIN_PROP_MAP=/* \ - END_PROP_MAP=*/// \ - BEGIN_MSG_MAP=/* \ - END_MSG_MAP=*/// \ - DECLARE_VIEW_STATUS=// \ - "STDMETHOD(a)=HRESULT a" \ - "ATL_NO_VTABLE= "\ - "__declspec(a)= "\ - BEGIN_CONNECTION_POINT_MAP=/* \ - END_CONNECTION_POINT_MAP=*/// -\endverbatim - -As you can see doxygen's preprocessor is quite powerful, but if you want -even more flexibility you can always write an input filter and specify it -after the \ref cfg_input_filter "INPUT_FILTER" tag. - -If you are unsure what the effect of doxygen's preprocessing will be -you can run doxygen as follows: -\verbatim - doxygen -d Preprocessor -\endverbatim -This will instruct doxygen to dump the input sources to standard output after -preprocessing has been done (Hint: set <code>QUIET = YES</code> and -<code>WARNINGS = NO</code> in the configuration file to disable any other -output). - -\htmlonly -Go to the <a href="faq.html">next</a> section or return to the - <a href="index.html">index</a>. -\endhtmlonly - -*/ |