Release-1.1.5-20000716

1 files changed, 211 insertions, 0 deletions

diff --git a/doc/docblocks.doc b/doc/docblocks.doc
new file mode 100644
index 0000000..f02d11f
--- /dev/null
+++ b/doc/docblocks.doc
@@ -0,0 +1,211 @@
+/******************************************************************************
+ *
+ * 
+ *
+ * Copyright (C) 1997-2000 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
+
+\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
+
+*/