diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Doxyfile | 11 | ||||
| -rw-r--r-- | doc/diagrams.doc | 137 | ||||
| -rw-r--r-- | doc/docblocks.doc | 211 | ||||
| -rw-r--r-- | doc/doxygen_manual.tex | 1 | ||||
| -rw-r--r-- | doc/doxysearch_usage.doc | 16 | ||||
| -rw-r--r-- | doc/doxytag_usage.doc | 3 | ||||
| -rw-r--r-- | doc/external.doc | 126 | ||||
| -rw-r--r-- | doc/faq.doc | 9 | ||||
| -rw-r--r-- | doc/features.doc | 12 | ||||
| -rw-r--r-- | doc/formulas.doc | 85 | ||||
| -rw-r--r-- | doc/grouping.doc | 108 | ||||
| -rw-r--r-- | doc/history.doc | 69 | ||||
| -rw-r--r-- | doc/index.doc | 8 | ||||
| -rw-r--r-- | doc/install.doc | 407 | ||||
| -rw-r--r-- | doc/language.doc | 14 | ||||
| -rw-r--r-- | doc/preprocessing.doc | 193 | ||||
| -rw-r--r-- | doc/starting.doc | 656 | ||||
| -rw-r--r-- | doc/trouble.doc | 14 |
18 files changed, 1293 insertions, 787 deletions
diff --git a/doc/Doxyfile b/doc/Doxyfile index d3aa4bc..2c5c5e4 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -27,11 +27,12 @@ GENERATE_HTML = YES GENERATE_HTMLHELP = YES GENERATE_RTF = NO ENABLE_PREPROCESSING = NO -INPUT = index.doc install.doc starting.doc faq.doc trouble.doc \ - history.doc features.doc \ - doxygen_usage.doc doxytag_usage.doc doxysearch_usage.doc \ - installdox_usage.doc output.doc autolink.doc \ - config.doc commands.doc htmlcmds.doc language.doc +INPUT = index.doc install.doc starting.doc docblocks.doc \ + grouping.doc formulas.doc diagrams.doc preprocessing.doc \ + external.doc faq.doc trouble.doc history.doc features.doc \ + doxygen_usage.doc doxytag_usage.doc doxysearch_usage.doc \ + installdox_usage.doc output.doc autolink.doc \ + config.doc commands.doc htmlcmds.doc language.doc FILE_PATTERNS = *.cpp *.h *.doc EXAMPLE_PATH = ../examples RECURSIVE = NO diff --git a/doc/diagrams.doc b/doc/diagrams.doc new file mode 100644 index 0000000..7fd3251 --- /dev/null +++ b/doc/diagrams.doc @@ -0,0 +1,137 @@ +/****************************************************************************** + * + * + * + * 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 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 + +*/ + 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 + +*/ diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex index 56f1242..4a89d23 100644 --- a/doc/doxygen_manual.tex +++ b/doc/doxygen_manual.tex @@ -51,6 +51,7 @@ Written by Dimitri van Heesch\\[2ex] \input{formulas} \input{diagrams} \input{preprocessing} +\input{external} \input{faq} \input{trouble} \part{Reference Manual} diff --git a/doc/doxysearch_usage.doc b/doc/doxysearch_usage.doc index a74d176..477d2d8 100644 --- a/doc/doxysearch_usage.doc +++ b/doc/doxysearch_usage.doc @@ -86,7 +86,7 @@ follow these steps: In fact the HTTP daemon that I tried (apache for Windows) only recognized <code>.cgi</code> files that were renamed executables (so DOS batch files do not seem to work either). Therefore, - on Windows a small C program will generated by doxygen. + on Windows a small C program will be generated by doxygen. You should compile and link the program with your favourite compiler and change the extension of the executable from <code>.exe</code> to <code>.cgi</code>. @@ -96,7 +96,7 @@ follow these steps: This is usually a special directory on your system or in your home directory. Consult the manual of your HTTP daemon or your system administrator to - find out, where this directory resides on your system. + find out where this directory resides on your system. <li>Goto the directory where the generated HTML files are located and run doxytag as follows: @@ -104,13 +104,11 @@ follow these steps: This will create a search index with the name <code>search.idx</code>. Currently the index file <em>must</em> be called like this. -<li>Run <a href="installdox_usage.html">installdox</a> to replace - any dummy links in the documentation with real links. - - \par Note: - When using a search engine this step is <em>required</em> - even if no tag files are used. If tag files are used you must specify - the correct options. +<li>If you change the location of the search engine or the documentation + and you do not want to regenerate the HTML output, you can simply edit + the generated search.cfg file and run the generated + <a href="installdox_usage.html">installdox</a> script to correct + the links in the documentation. </ol> diff --git a/doc/doxytag_usage.doc b/doc/doxytag_usage.doc index c6f0e3c..079e1b7 100644 --- a/doc/doxytag_usage.doc +++ b/doc/doxytag_usage.doc @@ -30,7 +30,8 @@ It has two functions: directly from the HTML files. This has the advantage that you do not need to have the sources from which the documentation was extracted. If you \e do have the sources it is better to let \c doxygen generate the - tag file by putting the name of the tag file after \c GENERATE_TAGFILE in + tag file by putting the name of the tag file after + \ref cfg_generate_tagfile "GENERATE_TAGFILE" in the configuration file. <li> Doxytag can generate a <em>search index</em> for the documentation diff --git a/doc/external.doc b/doc/external.doc new file mode 100644 index 0000000..01c275f --- /dev/null +++ b/doc/external.doc @@ -0,0 +1,126 @@ +/****************************************************************************** + * + * + * + * 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 external Linking to external documentation + +If your project depends on external libraries or tools, there are several +reasons to not include all sources for these with every run of doxygen: + +<dl> +<dt>Disk space:<dd> Some documentation may be available outside of the output + directory of doxygen already, for instance somewhere on the web. + You may want to link to these pages instead of generating the documentation + in your local output directory. +<dt>Compilation speed:<dd> External projects typically have a different update + frequency form your own project. It does not make much sense to let doxygen + parse the sources for these external project over and over again, even if + nothing has changed. +<dt>Memory:<dd> For very large source trees, letting doxygen parse all sources + may simply take too much of your system's memory. By dividing the sources + into several "packages", the sources of one package can be parsed by + doxygen, while all other packages that this package depends on, are + linked in externally. This saves a lot of memory. +<dt>Availability:<dd> For some projects that are documented with doxygen, + the sources may just not be available. +</dl> + +If any of the above apply, you can use doxygen's tag file mechanism. +A tag file is basically a compact representation of the entities found in the +external sources. Doxygen can both generate and read tag files. + +To generate a tag file for your project, simply put the name of the +tag file after the \ref cfg_generate_tagfile "GENERATE_TAGFILE" option in +the configuration file. + +To combine the output of one or more external projects with you own project +you should specify the name of the tag files after +the \ref cfg_tagfiles "TAGFILES" option in the configuration file. + +A tag file does not contain information about where the external documentation +is located. This could be a directory or URL. So when you include a tag +file you have to specify where the external documentation is located. +There are two ways to do this: +<dl> +<dt>At configuration time:<dd> just assign the location of the output to the + tag files specified after the \ref cfg_tagfiles "TAGFILES" configuration + option. If you use a relative path it should be relative with respect to + the directory where the html output of your project is generated. +<dt>After compile time:<dd> if you do not assign a location to a tag file, + doxygen will generate dummy links for all external HTML references. It will + also generate a perl script called \ref installdox_usage "installdox" in + the HTML output directory. This script should be run to replace the + dummy links with real links for all generated HTML files. +</dl> + +\par Example: +Suppose you have a project \c proj that uses two external +projects called \c ext1 and \c ext2. +The directory structure looks as follows: + +\par +\verbatim +<root> + +- proj + | +- html HTML output directory for proj + | +- src sources for proj + | |- proj.cpp + +- ext1 + | +- html HTML output directory for ext1 + | |- ext1.tag tag file for ext1 + +- ext2 + | +- html HTML output directory for ext2 + | |- ext2.tag tag file for ext2 + |- proj.cfg doxygen configuration file for proj + |- ext1.cfg doxygen configuration file for ext1 + |- ext2.cfg doxygen configuration file for ext2 +\endverbatim + +\par +Then relevate parts of the configuration files look as follows: +\par +proj.cfg: +\verbatim +OUTPUT_DIRECTORY = proj +INPUT = proj/src +TAGFILES = ext1/ext1.tag=../../ext1/html \ + ext2/ext2.tag=../../ext2/html +\endverbatim +ext1.cfg: +\verbatim +OUTPUT_DIRECTORY = ext1 +GENERATE_TAGFILE = ext1/ext1.tag +\endverbatim +ext2.cfg: +\verbatim +OUTPUT_DIRECTORY = ext2 +GENERATE_TAGFILE = ext2/ext2.tag +\endverbatim + +In some (hopefully exceptional) cases you may have the documentation +generated by doxygen, but not the sources nor a tag file. In this case you +can use the \ref doxytag_usage "doxytag" tool to extract a tag file from +the generated HTML sources. This tool depends on the particular structure +of the generated output and on some special markers that are generated by +doxygen. Since this type of extraction is brittle and error prone I +suggest to only use this approach if there is no alternative. The +doxytag tool may even become obsolete in the future. + +\htmlonly +Go to the <a href="faq.html">next</a> section or return to the + <a href="index.html">index</a>. +\endhtmlonly + +*/ diff --git a/doc/faq.doc b/doc/faq.doc index 08ea8d0..0817742 100644 --- a/doc/faq.doc +++ b/doc/faq.doc @@ -68,7 +68,7 @@ as <code>PREPROCESSING = YES</code>. Look at section \ref preprocessing for the answer. -<li><b>How can I change what's after the <code>#include</code> in class documentation?</b> +<li><b>How can I change what's after the <code>\#include</code> in the class documentation?</b> You can document your class like @@ -162,6 +162,13 @@ Simply put an exclude pattern like this in the configuration file: EXCLUDE_PATTERNS = */test/* \endverbatim +<li><b>Doxygen automatically generates a link to the + class MyClass somewhere in the running text. + How do I prevent that at a certain place?</b> + +Put a \% in front of the class name. Like this: \%MyClass. Doxygen will then +remove the % and keep the word unlinked. + </ol> \htmlonly diff --git a/doc/features.doc b/doc/features.doc index cec1dae..3298b0b 100644 --- a/doc/features.doc +++ b/doc/features.doc @@ -29,15 +29,17 @@ <li>JavaDoc (1.1), Qt-Doc, and KDOC compatible. <li>Automatically generates class diagrams in HTML (as clickable image maps) and \f$\mbox{\LaTeX}\f$ (as encapsulated postscript images). -<li>Using the dot tool of the Graphviz tool kit doxygen can generate +<li>Uses the dot tool of the Graphviz tool kit to generate include dependency graphs, collaboration diagrams, and graphical class hierarchy graphs. <li>Allows you to put documentation in the header file (before the declaration of an entity), source file (before the definition of an entity) or in a separate file. +<li>Can generate a list of all members of a class (including any inherited + members) along with their protection level. <li>Outputs documentation in on-line format (HTML and UNIX man page) and off-line format (\f$\mbox{\LaTeX}\f$) and RTF simultaniously - (any one can be disabled if desired). Both formats are optimized for + (any of these can be disabled if desired). All formats are optimized for ease of reading. <br> Furthermore, compressed HTML can be generated from HTML output using Microsoft's HTML help workshop (Windows only) and PDF can be generated @@ -54,9 +56,6 @@ generated automatically. <li>Includes a fast, rank based search engine to search for strings or words in the class and member documentation. -<li>Documentation may be placed either at the declaration or at the definition - of a member function or class. Most documentation systems (such as Javadoc) only - support the former, others (such as Qt) only the latter. <li>You can type normal HTML tags in your documentation. Doxygen will convert them to their equivalent \f$\mbox{\LaTeX}\f$ and man-page counterparts automatically. @@ -69,8 +68,9 @@ looking into the implementation details. <li>Allows automatic cross-referencing of (documented) entities with their definition in the source code. +<li>All source code fragments are syntax highlighted for ease of reading. <li>Allows inclusion of function/member/class definitions in the documentation. -<li>All options are read from an easy to edit and documented +<li>All options are read from an easy to edit and (optionally) annotated configuration file. <li>Documentation and search engine can be transferred to another location or machine without regenerating the documentation. diff --git a/doc/formulas.doc b/doc/formulas.doc new file mode 100644 index 0000000..347731b --- /dev/null +++ b/doc/formulas.doc @@ -0,0 +1,85 @@ +/****************************************************************************** + * + * + * + * 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 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 + +*/ diff --git a/doc/grouping.doc b/doc/grouping.doc new file mode 100644 index 0000000..2f1bef7 --- /dev/null +++ b/doc/grouping.doc @@ -0,0 +1,108 @@ +/****************************************************************************** + * + * + * + * 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 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 + +*/ diff --git a/doc/history.doc b/doc/history.doc index ed88fe2..aaa7e21 100644 --- a/doc/history.doc +++ b/doc/history.doc @@ -17,9 +17,38 @@ /*! \page history Doxygen History +<h3>Version 1.2.0</h3> +<h4>Major new features:</h4> +<ul> +<li>Support for RTF output. +<li>Using the dot tool of the AT&T's GraphViz package, doxygen can now + generate inheritance diagrams, collaboration diagrams, include + dependency graphs, included by graphs and graphical inheritance overviews. +<li>Function arguments can now be documentation with separate comment blocks. +<li>Initializers and macro definitions are now included in the documentation. +<li>Variables and typedefs are now put in their own section. +<li>Old configuration files can be upgraded using the -u option without + loosing any changes. +<li>Using the \\if and \\endif commands, doxygen can conditionally + include documentation blocks. +<li>Added Doc++ like support for member grouping. +<li>Doxygen now has a GUI front-end called doxywizard (based on Qt-2.1) +<li>All info about configuration options is now concentrated in a new + tool called configgen. This tool can generate the configuration + parser and GUI front-end from source templates. +<li>Better support for the using keyword. +<li>New transparent mini logo that is put in the footer of all HTML pages. +<li>Internationalization support for the Polish and Croatian language. +<li>Todo list support. +<li>If the source browser is enabled, for a function, a list of function whose + implementation calls that function, is generated. +<li>All source code fragments are now syntax highlighted in the HTML output. + The colors can be changed using cascading style sheets. +</ul> + <h3>Version 1.0.0</h3> -<h4>New features:</h4> +<h4>Major new features:</h4> <ul> <li>Support for templates and namespaces. <li>Internationalization support. Currently supported languages are: @@ -36,7 +65,7 @@ <h3>Version 0.4</h3> -<h4>New features:</h4> +<h4>Major new features:</h4> <ul> <li>LaTeX output generation. <li>Full JavaDoc support. @@ -52,14 +81,9 @@ <li>Completely new documentation, that is now generated by Doxygen. <li>A lot of small examples are now included. </ul> -<h4>Bug fixes:</h4> -<ul> -<li>A lot of parser bugs are fixed. -<li>Improved support for documenting C code. -</ul> <h3>Version 0.3</h3> -<h4>New features:</h4> +<h4>Major new features:</h4> <ul> <li>A search engine <a href="doxysearch_usage.html">doxysearch</a>, that allows you to search through the generated documentation. @@ -75,24 +99,8 @@ documentation. </ul> -<h4>Bug fixes:</h4> -<ul> -<li>Fixed bug when files with the same name but in different directories - are used as include files. -<li>Template classes now work. -<li>Inner classes now work. -<li>Fixed a bug regarding unrelated functions and <code>\fn</code>. -<li>Fixed parse bug with <code>/**/</code> comments -<li>Fixed a bug regarding inline friend functions. -<li>The list of all members now also contains the undocumented members. -<li>Special documentation is now removed from code blocks. -<li>Doxygen should compile on Sun Solaris (with <code>CC</code>), HP-UX (with - <code>CC</code>), Irix (with DCC) and Linux (with <code>GCC</code>) -<li>Fixed several minor bugs. -</ul> - <h3>Version 0.2</h3> -<h4>New features:</h4> +<h4>Major new features:</h4> <ul> <li>Blocks of code are now parsed. Function calls and variables are replaced by links to their documentation if possible. @@ -112,17 +120,6 @@ instead of only the used ones. </ul> -<h4>Bug fixes:</h4> -<ul> -<li>Fixed a link generation problem with mixed case filenames are used. -<li>Made doxygen a little more portable. - (doxygen should now compile on Linux (with g++) and HP-UX (with CC)) -<li>Fixed a bug in err() function. -<li>Fixed a problem with the type cast operator. -<li>Removed some typo's from the docs. -<li>Several small bug fixes and enhancements. -</ul> - <h3>Version 0.1</h3> Initial version. diff --git a/doc/index.doc b/doc/index.doc index 1c52565..6256799 100644 --- a/doc/index.doc +++ b/doc/index.doc @@ -91,6 +91,7 @@ The first part forms a user manual: <li>Section \ref formulas shows how to insert formulas in the documentation. <li>Section \ref diagrams describes the diagrams and graphs that doxygen can generate. <li>Section \ref preprocessing explains how doxygen deals with macro definitions. +<li>Section \ref external explains how to let doxygen create links to externally generated documentation. <li>Section \ref faq gives answers to frequently asked questions. <li>Section \ref trouble tells you what to do when you have problems. </ul> @@ -165,9 +166,10 @@ Thanks go to: sources. <li>Tim Mensch for adding the todo command. <li>Jens Breitenstein, Christophe Bordeaux, Samuel Hägglund, Xet Erixon, - Vlastimil Havran, Ahmed Also Faisal, Alessandro Falappa, Kenji Nagamatsu, - Francisco Oltra Thennet, Olli Korhonen for providing translations into - various languages. + Vlastimil Havran, Petr Prikryl, Ahmed Also Faisal, Alessandro Falappa, + Kenji Nagamatsu, Francisco Oltra Thennet, Olli Korhonen, + Boris Bralo, Nickolay Semyonov, and Grzegorz Kowal for providing + translations into various languages. <li> Arnt Gulbrandsen, Adam P. Jenkins, diff --git a/doc/install.doc b/doc/install.doc index 461e730..c03a529 100644 --- a/doc/install.doc +++ b/doc/install.doc @@ -20,96 +20,395 @@ First go to the <a href="http://www.stack.nl/~dimitri/doxygen/download.html">download</a> page \latexonly({\tt http://www.stack.nl/$\sim$dimitri/doxygen/download.html})\endlatexonly -to get the latest distribution and unpack it. +to get the latest distribution, if you did not have it already. + +\subsection install_src_unix Compiling from source on Unix If you downloaded the source distribution, you need at least the following to build the executable: -<UL> -<LI>Troll Tech's GUI toolkit <A HREF="http://www.trolltech.com/products/qt.html">Qt</A> +<ul> +<li>Troll Tech's GUI toolkit + <A HREF="http://www.trolltech.com/products/qt.html">Qt</A> \latexonly(see {\tt http://www.trolltech.com/products/qt.html})\endlatexonly. \addindex Qt -<LI>The <a href="ftp://prep.ai.mit.edu/pub/gnu">GNU</a> tools + You can download either version 1.44 or version 2.1.x. + If want to build the GUI front-end you will need Qt 2.1.x. If you do + not need it, using Qt 1.44 will result in a somewhat smaller executable. +<li>The <a href="ftp://prep.ai.mit.edu/pub/gnu">GNU</a> tools flex, bison and make \addindex flex \addindex bison \addindex make -<LI>In order to generate a Makefile for your platform, you need +<li>In order to generate a Makefile for your platform, you need <a href="http://www.perl.com>perl</a> \latexonly(see {\tt http://www.perl.com})\endlatexonly. \addindex perl -</UL> -For platform specific installation instructions see the \c INSTALL file -that is included in the package. +</ul> + +To take full advantage of doxygen's features the following additional +tools should be installed. + +<ul> +<li>A \f$\mbox{\LaTeX}\f$ distribution: for instance + <a href="http://www.tug.org">teTeX 1.0</a>.<br> + This is needed for generating LaTeX, Postscript, and PDF output. +<li><a href="http://www.research.att.com/sw/tools/graphviz/"> + the Graph visualization toolkit version 1.5</a><br> + Needed for the include dependency graphs, + the graphical inheritance graphs, + and the collaboration graphs. +<li>The ghostscript interpreter. +</ul> + +Compilation is now done by performing the following steps: + +<ol> +<li> Unpack the archive, unless you already have done that: + +\verbatim + gunzip doxygen-$VERSION.src.tar.gz # uncompress the archive + tar xf doxygen-$VERSION.src.tar # unpack it +\endverbatim + +<li>Run the configure script: + +\verbatim + sh ./configure +\endverbatim -\addindex HTTP -\addindex CGI -To use the search engine \c doxysearch, you will also need -a HTTP daemon running on the target system and permission to execute a -CGI binary. + The script tries to determine the platform you use, the location + of the Qt library, the make tool (which \e must be GNU make) and the perl + interpreter. It will report what it finds. + + To override the auto detected platform and compiler you can run + configure as follows: -If you are running Unix, and have Qt installed correctly, you can simply enter \verbatim -configure + configure --platform platform-type \endverbatim -to set up the makefiles for your platform. For Windows this step can be -skipped. -To override the auto detected platform you can specify + See the <code>PLATFORMS</code> file for a list of possible platform + options. + + If you have Qt-2.1.x installed and want to build the GUI front-end, you + should run the configure script with the <code>--with-doxywizard</code> + option. + + For an overview of other configuration options use + \verbatim -configure --platform platform-type + configure --help \endverbatim -See the file \c PLATFORMS for a list of possible platforms. -For more configuration options use <code>configure --help</code> -To compile and link the sources enter +<li>Compile the program by running make: + \verbatim -make + make \endverbatim -in the root of the distribution. -Doxygen should compile without errors or warnings. -If it does not, please send the compilation errors or warnings along -with a description of your platform to -<a href="mailto:dimitri@stack.nl>dimitri@stack.nl</a>. -After compilation, the binaries will be located in the \c bin -directory of the distribution. -You may want to copy these files to a location in your path -(\c /usr/local/bin for instance) or add the \c bin -directory of the distribution to your search path. + The program should compile without problems and three binaries + (<code>doxygen</code>, <code>doxytag</code>, and <code>doxysearch</code>) + should be available in the bin directory of the distribution. -On Unix you can also type: +<li>Optional: Generate the user manual. + \verbatim -make install + make docs \endverbatim -The following binaries should now be available: -<UL> -<LI>\c doxygen: for generating the class browser. -<LI>\c doxytag: for creating a tag file containing references - to external documentation. -<LI>\c doxysearch: the search engine. This binary should not be - executed directly. It must be called from an CGI script that will be - generated by doxygen. -</UL> + To let doxygen generate the HTML documentation. + + \note you will need the stream editor <code>sed</code> for this, + but this should be available on any Unix platform. -To take full advantage of doxygen's features the following additional -tools should be installed. + The HTML directory of the distribution will now contain the html + documentation (just point a HTML browser to the file + <code>index.html</code> in the + html directory). + +<li>Optional: Generate a postscript and pdf version of the manual. + (you will need <code>latex</code> and <code>dvips</code> and + the ghostscript package for this). + +\verbatim + make pdf +\endverbatim + The postscript manual <code>doxygen_manual.ps</code> will be located + in the latex directory of the distribution. Just send it to a + postscript printer to print it or use <code>ghostview</code> to view it. + +</ol> + +\subsection install_bin_unix Installating the binaries on Unix + + If you downloaded the binary distribution for Unix, you can install + doxygen by typing: + +\verbatim + ./configure + make install +\endverbatim + + Binaries are installed in the directory <code>\<prefix\>/bin</code> + Documentation and examples in the directory + <code>\<prefix\>/doc/doxygen</code> + + <code>\<prefix\></code> defaults to /usr but can be changed with + the <code>--prefix</code> option of the configure script. + + Alternatively, you can also copy the binaries from the <code>bin</code> + directory manually to some <code>bin</code> directory in your search path. + This is sufficient to use doxygen. + + \note You need the GNU install tool for this to work. Other + install tools may put the binaries in the wrong directory! + + If you have a RPM or DEP package, then please follow the + standard installation procedure that is required for these packages. + +\subsection unix_problems Known compilation problems for Unix + +<b>Qt problems</b> + +The Qt include files and libraries are not a sub directory of the +directory pointed to by QTDIR on some systems. +(for instance on Red Hat 6.0 includes are in /usr/include/qt and +libs are in /usr/lib) + +The solution: goto the root of the doxygen distribution and do: +\verbatim + mkdir qt + cd qt + ln -s your-qt-include-dir-here include + ln -s your-qt-lib-dir-here lib + export QTDIR=$PWD +\endverbatim + +If you have a csh-like shell you should use <code>setenv QTDIR $PWD</code> +instead of the <code>export</code> command above. + +Now install doxygen as described above. + +<b>Latex problems</b> + +the file <code>a4wide.sty</code> is not available for all distributions. If +your distribution does not have it please select another paper type +in the config file (see the \ref cfg_paper_type "PAPER_TYPE" tag in the +config file). + +<b>HP-UX & Digital Unix problems</b> + +If you are compiling for HP-UX with aCC and you get this error: +\verbatim + /opt/aCC/lbin/ld: Unsatisfied symbols: + alloca (code) +\endverbatim + then you should (according to Anke Selig) edit <code>ce_parse.cpp</code> + and replace +\verbatim + extern "C" { + void *alloca (unsigned int); + }; +\endverbatim + with +\verbatim + #include <alloca.h> +\endverbatim + +If you are compiling for Digital Unix, the same problem can be solved +(according to Barnard Schmallhof) by replacing the following in +ce_parse.cpp: + +\verbatim + #else /* not GNU C. */ + #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) + #include <alloca.h> +\endverbatim + + with + +\verbatim + #else /* not GNU C. */ + #if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) || defined (__osf__) + #include <alloca.h> +\endverbatim + + Alternatively, one could fix the problem at the bison side. + Here is patch for bison.simple (provided by Andre Johansen): + +\verbatim +--- bison.simple~ Tue Nov 18 11:45:53 1997 ++++ bison.simple Mon Jan 26 15:10:26 1998 +@@ -27,7 +27,7 @@ + #ifdef __GNUC__ + #define alloca __builtin_alloca + #else /* not GNU C. */ +-#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) ++#if (!defined (__STDC__) && defined (sparc)) || defined (__sparc__) || defined (__sparc) || defined (__sgi) || defined (__alpha) + #include <alloca.h> + #else /* not sparc */ + #if defined (MSDOS) && !defined (__TURBOC__) +\endverbatim + + The generated scanner.cpp that comes with doxygen is build with this + patch applied. + +<b>Sun compiler problems</b> + + + +<b>GNU 2.7.2.x compiler problems</b> + +Older versions of the GNU compiler have problems with constant strings +containing characters with character codes larger than 127. Therefore +the compiler will fail to compile some of the translator_xx.h files. +A workaround, if you are planning to use the English translation only, +is to configure doxygen with the <code>--english-only</code> option. + +\subsection install_src_windows Compiling from source on Windows + +Currently, I have only compiled doxygen for Windows using Microsoft's +Visual C++ (version 6.0). For other compilers you may need to edit the +perl script in <code>wintools/make.pl</code> a bit. +Let me know what you had to change if you got Doxygen working with another +compiler. + +Since Windows comes without all the nice tools that Unix users are +used to, you need to install a number of these tools before you can compile +doxygen for Windows. + +Here is what is required: <ul> -<li>\f$\mbox{\LaTeX}\f$: - <a href="http://www.tug.org">teTeX 1.0</a> (for Unix) or - <a href="ftp://ctan.tug.org/tex-archive/systems/win32/web2c/fptex-0.3/">fpTeX 0.3</a> (for Windows)<br> - Needed for LaTeX and PDF output. +<li>WinZip to unpack the tar source distribution. This can be found at + http://www.winzip.com +<li>Microsoft Visual C++ (I only tested with version 6.0). + Use the <code>vcvars32.bat</code> batch file to set the environment + variables (if you did not select to do this automatically during + installation). +<li>Perl 5.0 or higher for Windows. This can be download from: + http://www.ActiveState.com/pw32 +<li>The GNU tools flex, bison and sed. + To get these working on Windows you should install the + <a href="http://sourceware.cygnus.com/cygwin/">cygwin tools</a> + \latexonly(see {\tt http://sourceware.cygnus.com/cygwin/})\endlatexonly. + + Make sure the <code>BISONLIB</code> environment variable points to the + location where the files <code>bison.simple</code> and + <code>bison.hairy</code> are located. + + Also make sure the tools are available from a dos box, by adding + the directory they are in to the search path. + +<li>A professional license of + <A HREF="http://www.trolltech.com/products/qt.html">Qt for Windows</A><br> + \latexonly(see {\tt http://www.trolltech.com/products/qt.html})\endlatexonly. + + If you do not have that and you can live without the GUI front-end + you can also download Qt-1.44 for X11. Doxygen only the depends on + the tools section of the Qt library, which happens also to compile + on Windows. (Qt version 2.1.x does not work anymore, at least not + without adding some window's specific code). + + Now create the following directories: + +\verbatim + qtools/src + qtools/include + qtools/lib +\endverbatim + + Copy the contents of the <code>src/tools</code> directory of the + Qt-1.44 for X11 archive to <code>qtools/src</code>. Also copy the include + files in <code>src/tools</code> to <code>qtools/include</code>. Create a + static library project resulting in <code>qtools/lib/qt.lib</code> and + add the files in <code>qtools/src</code> to that project. Then + build the library and set the environment variable <code>QTDIR</code> + to the absolute path of the qtools directory. + +<li>To generate LaTeX documentation or formulas in HTML you need the tools: + latex, dvips and gswin32 + To get these working under Windows install the fpTeX distribution + You can download it at: + ftp://ctan.tug.org/tex-archive/systems/win32/web2c/fptex-0.3/ + + Make sure the tools are available from a dos box, by adding the + directory they are in to the search path. + +<li>If you want to generate compressed HTML help + (see \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP") in the + config file, then you need the Microsoft HTML help workshop. + You can download it at: + http://msdn.microsoft.com/workshop/author/htmlhelp +<li>If you used WinZip to extract the tar archive it will (apparently) not + create empty folders, so you have to add the folders + <code>objects</code> and <code>bin</code> manually in the root of the + distribution before compiling. <li><a href="http://www.research.att.com/sw/tools/graphviz/"> the Graph visualization toolkit version 1.5</a><br> Needed for the include dependency graphs, the graphical inheritance graphs, and the collaboration graphs.<br> -<li><a href="http://msdn.microsoft.com/workshop/author/htmlhelp"> - the HTML help workshop</a> (for Windows only)<br> - Needed for compiling compressed HTML output (a.k.a. the new Windows help format). </ul> -Doxygen was developed and tested under Linux using the following tools: +Compilation is now done by performing the following steps: + +<ol> +<li>Open a dos box. + Make sure all tools (i.e. <code>nmake</code>, <code>latex</code>, + <code>gswin32</code>, <code>dvips</code>, <code>sed</code>, + <code>flex</code>, <code>bison</code>, + <code>cl</code>, <code>rm</code> and <code>perl</code>), are accessible from the command-line + (add them to the PATH environment variable if needed). + +<li>goto the doxygen root dir and type: + +\verbatim + make.bat +\endverbatim + + This should build the executables + <code>doxygen.exe</code>, <code>doxytag.exe</code>, and + <code>doxysearch.exe</code> (The compiler should not produce any + serious warnings or errors). + +<li>To build the examples type: + +\verbatim + nmake examples +\endverbatim + +<li>To generate the HTML documentation type: + +\verbatim + nmake docs +\endverbatim + + The generated docs are located in the html directory. + +<li> + To generate the postscript and PDF manual type: + +\verbatim + nmake pdf +\endverbatim + + The manual should now be in <code>latex/doxygen_manual.pdf</code> + +</ol> + +\subsection install_bin_windows Installating the binaries on Windows + +There is no fancy installation procedure at the moment (If anyone wants +to add it please let me know). + +To install doxygen, just copy the binaries from the <code>bin</code> directory +to a location somewhere in the path. Alternatively, you can include +the <code>bin</code> directory of the distribution to the path. + +\subsection build_tools Tools used to develop doxygen + +Doxygen was developed and tested under Linux using the following +open-source tools: <ul> <li>EGCS version 2.91.66 <li>GNU flex version 2.5.4 diff --git a/doc/language.doc b/doc/language.doc index 9beb124..0c19968 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -94,18 +94,6 @@ Here is a list of the languages and their current maintainers: </TR> <TR BGCOLOR="#ffffff"> <TD> - Romanian - </TD> - <TD> - Ionutz Borcoman - </TD> - <TD> - <a href="mailto:borco@NOSPAM.borco-ei.eng.hokudai.ac.jp"> - borco@NOSPAM.borco-ei.eng.hokudai.ac.jp</a> - </TD> - </TR> - <TR BGCOLOR="#ffffff"> - <TD> Italian </TD> <TD> @@ -226,8 +214,6 @@ Here is a list of the languages and their current maintainers: Czech & Petr Prikryl & {\tt prikrylp@skil.cz} \\ & Vlastimil Havran & {\tt havran@fel.cvut.cz} \\ \hline - Romanian & Ionutz Borcoman & {\tt borco@borco-ei.eng.hokudai.ac.jp} \\ - \hline Italian & Ahmed Aldo Faisal & {\tt aaf23@cam.ac.uk} \\ & Alessandro Falappa & {\tt a.falappa@flashnet.it} \\ \hline diff --git a/doc/preprocessing.doc b/doc/preprocessing.doc new file mode 100644 index 0000000..2e1ee36 --- /dev/null +++ b/doc/preprocessing.doc @@ -0,0 +1,193 @@ +/****************************************************************************** + * + * + * + * 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 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="external.html">next</a> section or return to the + <a href="index.html">index</a>. +\endhtmlonly + +*/ 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 - -*/ diff --git a/doc/trouble.doc b/doc/trouble.doc index a69aba0..3fac65e 100644 --- a/doc/trouble.doc +++ b/doc/trouble.doc @@ -18,15 +18,16 @@ <h2>Known problems:</h2> <ul> -<li>Doxygen is <em>not</em> a compiler, it is only a lexical scanner. +<li>Doxygen is <em>not</em> a real compiler, it is only a lexical scanner. This means that it can and will not detect errors in your source code. <li>Since it impossible to test all possible code fragments, it is very well possible, that some valid piece of C/C++ code is not handled properly. If you find such a piece, please send it to me, so I can improve doxygen's parsing capabilities. Try to make the piece of code you send as small as possible, to help me narrow down the search. -<li>Using declarations are not yet supported. They are simply ignored. - Using directives are supported however. +<li>Using declarations for member are not yet supported. + They are simply ignored. Using declarations for class and using + directives are supported however. <li>Doxygen does not work properly if there are multiple classes, structs or unions with the same name in your code. It should not crash however, rather it should ignore all of the classes with the same name except one. @@ -52,6 +53,9 @@ then doxygen will remove the braces and correctly parse the result. <li>Not all names in code fragments that are included in the documentation are replaced by links (for instance when using \c SOURCE_BROWSER = \c YES). + This also holds for the "Referenced by" list that is generated for + each function. + For a part this is because the code parser isn't smart enough at the moment. I'll try to improve this in the future. But even with these improvements not everthing can be properly linked to the corresponding @@ -60,6 +64,10 @@ <li>It is not possible to insert a non-member function f in a class A using the \relates command, if class A already has a member with name f and the same argument list. +<li>There is only very limited support for member specialization at the + moment. It only works if there is a specialized template class as + well. +<li>Not all special commands are properly translated to RTF. </ul> |