summaryrefslogtreecommitdiffstats
path: root/doc/starting.doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/starting.doc')
-rw-r--r--doc/starting.doc656
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
-
-*/