summaryrefslogtreecommitdiffstats
path: root/doc/starting.doc
diff options
context:
space:
mode:
authormueller <mueller@afe2bf4a-e733-0410-8a33-86f594647bc7>1999-12-15 19:25:10 (GMT)
committermueller <mueller@afe2bf4a-e733-0410-8a33-86f594647bc7>1999-12-15 19:25:10 (GMT)
commit719f0a35063be88eddcc4ed8fe7a940de47ef20c (patch)
treecc1cd70cf5761ddf72ff114c0b65576c3f4c1d2a /doc/starting.doc
parentbd30c025c4651ddda467f1af09d4c7ccab397bde (diff)
downloadDoxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.zip
Doxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.tar.gz
Doxygen-719f0a35063be88eddcc4ed8fe7a940de47ef20c.tar.bz2
initial version
Diffstat (limited to 'doc/starting.doc')
-rw-r--r--doc/starting.doc411
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
+
+*/