diff options
Diffstat (limited to 'doc/starting.doc')
| -rw-r--r-- | doc/starting.doc | 411 |
1 files changed, 411 insertions, 0 deletions
diff --git a/doc/starting.doc b/doc/starting.doc new file mode 100644 index 0000000..1d3cbcd --- /dev/null +++ b/doc/starting.doc @@ -0,0 +1,411 @@ +/****************************************************************************** + * + * $Id$ + * + * Copyright (C) 1997-1999 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. + * + * All output generated with Doxygen is not covered by this license. + * + */ +/*! \page starting Getting started + +The executable \c doxygen is the main program that parses the sources and +generates the documentation. See section \ref doxygen_usage for more +detailed usage information. + +The executable \c doxytag is only needed if you want to generate references +to external documentation (i.e. documentation that was generated by Doxygen) +for which you do not have the sources or to create a search index for +the search engine. See section \ref doxytag_usage for more detailed usage +information. + +The executable \c doxysearch is only needed if you want to use the search +engine. See section \ref doxysearch_usage for more detailed usage information. + +\subsection step1 Step 1: Creating a configuration file + +Doxygen uses a configuration file to determine all of its settings. +Each project should get its own configuration file. A project can consist +of a single source file, but can also be an entire source tree that is +recursively scanned. + +To simplify the creation of a configuration file, Doxygen can create a +template configuration file for you. To do this call \c doxygen with the \c -g +option: + +\verbatim +doxygen -g <config-file> +\endverbatim +where \<config-file\> is the name of the configuration file. If you omit +the file name, a file named \c Doxyfile will be created. If a file with the +name \<config-file\> already exists, Doxygen will rename it to +\<config-file\>.bak before generating the configuration template. + +The configuration file has a format that is similar to that of a (simple) +Makefile. It contains of a number of assignments (tags) of the form: + +<tt>TAGNAME = VALUE</tt> or <br> +<tt>TAGNAME = VALUE1 VALUE2 ... </tt><br> + +You can probably leave the values of most tags to their default value. + +The \c INPUT tag is the only tag for which you are required to provide +a value. See section \ref config for more details about the configuration file. +For a small project consisting of a few C and/or C++ source and header files, +you can add the names of the files after the \c INPUT tag. +If you have a larger project consisting of a source directory or tree +this may become tiresome. In this case you should put the root directory or +directories after the \c INPUT tag, and add one or more file +patterns to the \c FILE_PATTERN tag. Only files that match one of the +patterns will be parsed (if the patterns are omitted all files will be parsed). +For recursive parsing of a source tree you must set +the \c RECURSIVE tag to \c YES. To further finetune the list of files +that is parsed the \c EXCLUDE and \c EXCLUDE_PATTERNS tags can be used. + +If you start using Doxygen for an existing project (thus without any +documentation that Doxygen is aware of), you can still get an idea of +what the documented result would be. To do so, you must set the \c EXTRACT_ALL +tag in the configuration file to \c YES. Then, Doxygen will pretend +everything in your sources is documented. Please note that warnings of +undocumented members will not be generated as long as \c EXTRACT_ALL is set +to \c YES. + +\subsection step2 Step 2: Running doxygen + +To generate the documentation you can now enter: +\verbatim +doxygen <config-file> +\endverbatim + +Doxygen will create a \c html, \c latex and/or \c man directory inside +the output directory. +As the names suggest the \c html directory contains the +generated documentation in HTML format and the \c latex directory contains the +generated documentation in \f$\mbox{\LaTeX}\f$ format. Man pages are put +in a man3 directory inside the \c man directory. + +The default output directory is the directory in which \c doxygen +is started. The directory to which the output is written can be changed +using the \c OUTPUT_DIRECTORY , \c HTML_OUTPUT, \c LATEX_OUTPUT, and +\c MAN_OUTPUT tags of the configuration file. If the output directory does not +exist, \c doxygen will try to create it for you. + +\addindex browser +The generated HTML documentation can be viewed by pointing a HTML browser +to the \c index.html file in the \c html directory. For the best results +a browser that supports cascading style sheets (CSS) should be used +(I'm currently using Netscape 4.0 to test the generated output). +\addindex LaTeX + +The generated \f$\mbox{\LaTeX}\f$ documentation must first be compiled by +a \f$\mbox{\LaTeX}\f$ compiler. (I use teTeX distribution version 0.4 +that contains \f$\mbox{\TeX}\f$ version 3.14159). To simplify the process +of compiling the generated +documentation, \c doxygen writes a \c Makefile into the \c latex directory. +By typing \c make in the \c latex directory the dvi file \c refman.dvi +will be generated. This file can then be viewed using \c xdvi or +converted into a postscript file \c refman.ps by typing <code>make ps</code> +(this requires \c dvips ). The Postscript file can be send to a postscript +printer. If you do not have a postscript printer, you can try to use +ghostscript to convert postscript into something your printer understands. + +The generated man pages can be viewed using the \c man program. You do need +to make sure the man directory is in the man path (see the MANPATH +environment variable). Notice that there are some limitations to the +capabilities of the man page format, so some information +(like class diagrams, cross references and formulas) will be lost. + +\subsection step3 Step 3: Documenting the sources + +Although documenting the source is presented as step 3, in a new project +this should ofcourse be step 1. Here I assume +you already have some code and you want Doxygen to generate a nice document +describing the API and maybe the internals as well. + +If the \c EXTRACT_ALL option is set to \c NO in the configuration file +(the default), then doxygen will only generate documentation for +\e documented members, files, classes and namespaces. So how do you document +these? For members, classes and namespaces there are basicly two options: +<ol> +<li>Place a \e special documentation block in front of the declaration or + definition of the member, class or namespace. For file, class and namespace + members it is also allowed to place the documention directly after the + member. See section \ref specialblock to learn more about special + documentation blocks. +<li>Place a special documentation block somewhere else (another file or + another location) \e and put a <em>structural command</em> in the + documentation block. A structural command links a documentation block + to a certain object that can be documented (e.g. a member, class, + namespace or file). See section \ref structuralcommands to learn more + about structural commands. +</ol> +Files can only be documented using the second option. +The text inside a special documentation block is parsed +before it is written to the HTML and/or \f$\mbox{\LaTeX}\f$ output files. + +\addindex parsing +During parsing the following steps take place: +<ul> +<li> The special commands inside the documentation are executed. See + section \ref commands for an overview of all commands. +<li> If a line starts with some whitespace followed by one or more asterixes + (<tt>*</tt>) then the whitespace and asterixes are removed. +<li> All resulting blank lines are treated as a paragraph separators. + This saves you from placing new-paragraph commands yourself, + in order to make the generated documentation readable. +<li> Links are created for words corresponding to documented classes. +<li> Links to members are created when certain patterns are found in the + text. See section \ref autolink + for more information on how the automatic link generation works. +<li> HTML tags that are in the documentation are interpreted and converted + to \f$\mbox{\LaTeX}\f$ equivalents for the \f$\mbox{\LaTeX}\f$ output. + See section \ref htmlcmds for an overview of all supported HTML tags. +</ul> + +\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> + +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 omitted by setting \c 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 \c 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 + +Notice that 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. The brief description is required for the +JavaDoc style. + +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). + +\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. Notice 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 Notice: + 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 +Notice 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 file classes, unions, structs and + enums. Furthermore, the structural commands mentioned in the + previous section are ignored inside these comment blocks. + +\subsection formulas Including formulas in the documentation + +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.4 distribution. +<li>\c dvips: a tool to convert dvi files to postscript files + I have used version 5.58f from Radical Eye software for testing. +<li>\c gs: the ghostscript interpreter for converting postscript files + to bitmaps. I have used Aladdin Ghostscript 5.01 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 formula.repository that is written in the html directory to +a rid of an incorrect formula + +\subsection moreinfo More information + +\addindex QdbtTabular +For a more elaborate example see <a href="http://www.stack.nl/~dimitri/qdbttabular/html/index.html"> +the documentation of QdbtTabular</a> \latexonly +({\tt http://www.stack.nl/$\sim$dimitri/qdbttabular/html})\endlatexonly. +\htmlonly +I hope that was clear. If not, please let me know, so I can improve this document. If you have problems +take a look at the <a href="trouble.html">troubleshooting</a> section. +\endhtmlonly + +*/ |