index.doc 9.09 KB
Newer Older
mueller's avatar
mueller committed
1 2
/******************************************************************************
 *
dimitri's avatar
dimitri committed
3
 * 
mueller's avatar
mueller committed
4
 *
dimitri's avatar
dimitri committed
5
 * Copyright (C) 1997-2008 by Dimitri van Heesch.
mueller's avatar
mueller committed
6 7 8 9 10 11 12
 *
 * 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.
 *
dimitri's avatar
dimitri committed
13 14
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
mueller's avatar
mueller committed
15 16
 *
 */
dimitri's avatar
dimitri committed
17
/*! \page index 
dimitri's avatar
dimitri committed
18
\if logo_on
mueller's avatar
mueller committed
19 20
<center>
\htmlonly
dimitri's avatar
dimitri committed
21
<img src="doxygen_logo.gif" width="634" height="197" alt="doxygen"/><br/>
mueller's avatar
mueller committed
22 23 24
Version: $(VERSION)
\endhtmlonly
</center>
dimitri's avatar
dimitri committed
25
\endif
mueller's avatar
mueller committed
26 27

<h2>Introduction</h2>
dimitri's avatar
dimitri committed
28
Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL 
dimitri's avatar
dimitri committed
29
(Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.
mueller's avatar
mueller committed
30

dimitri's avatar
dimitri committed
31 32 33 34 35 36
It can help you in three ways:
<ol>
<li> It can generate an on-line documentation browser (in HTML) and/or an 
     off-line reference manual (in \f$\mbox{\LaTeX}\f$) from a set 
     of documented source files. 
     There is also support for generating output in RTF (MS-Word), 
dimitri's avatar
dimitri committed
37
     PostScript, hyperlinked PDF, compressed HTML, and Unix man pages.
dimitri's avatar
dimitri committed
38 39 40
     The documentation is extracted directly from the sources, which
     makes it much easier to keep the documentation consistent with the
     source code.
dimitri's avatar
dimitri committed
41
<li> You can \ref extract_all "configure" doxygen to extract the code structure 
dimitri's avatar
dimitri committed
42
     from undocumented source files. This is very useful to quickly 
dimitri's avatar
dimitri committed
43
     find your way in large source distributions. 
dimitri's avatar
dimitri committed
44
     You can also visualize the relations between the various elements 
dimitri's avatar
dimitri committed
45 46 47 48 49
     by means of include dependency graphs, inheritance diagrams,
     and collaboration diagrams, which are all generated automatically.
<li> You can even `abuse' doxygen for creating normal documentation (as I did
     for this manual).
</ol>
mueller's avatar
mueller committed
50

dimitri's avatar
dimitri committed
51 52 53 54
Doxygen is developed under <a href="http://www.linux.org">Linux</a>
and Mac OS X, but is set-up to be highly portable. As a result, it 
runs on most other Unix flavors as well. Furthermore, executables for 
Windows are available.
mueller's avatar
mueller committed
55

dimitri's avatar
dimitri committed
56
\n This manual is divided into three parts, each of which is divided into several 
mueller's avatar
mueller committed
57 58 59 60
sections.

The first part forms a user manual:
<ul>
mueller's avatar
mueller committed
61
<li>Section \ref install discusses how to 
dimitri's avatar
dimitri committed
62
      <a href="http://www.doxygen.org/download.html">download</a>, compile and install
mueller's avatar
mueller committed
63 64 65
                     doxygen for your platform.
<li>Section \ref starting tells you how to generate your first piece of 
                     documentation quickly. 
dimitri's avatar
dimitri committed
66 67
<li>Section \ref docblocks demonstrates the various ways that code can
                 be documented.
dimitri's avatar
dimitri committed
68
<li>Section \ref lists show various ways to create lists. 
dimitri's avatar
dimitri committed
69
<li>Section \ref grouping shows how to group things together. 
dimitri's avatar
dimitri committed
70 71 72
<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.
dimitri's avatar
dimitri committed
73 74 75 76
<li>Section \ref autolink shows how to put links to files, classes, 
                 and members in the documentation.
<li>Section \ref output shows how to generate the various output formats
                 supported by doxygen.
dimitri's avatar
dimitri committed
77
<li>Section \ref searching shows various ways to search in the HTML documentation.
dimitri's avatar
dimitri committed
78 79
<li>Section \ref customize explains how you can customize the output generated
                 by doxygen.
dimitri's avatar
dimitri committed
80
<li>Section \ref custcmd show how to define and use custom commands in your comments.
dimitri's avatar
dimitri committed
81
<li>Section \ref external explains how to let doxygen create links to externally generated documentation.
mueller's avatar
mueller committed
82
<li>Section \ref faq gives answers to frequently asked questions. 
mueller's avatar
mueller committed
83 84 85 86 87 88
<li>Section \ref trouble tells you what to do when you have problems.
</ul>

The second part forms a reference manual:

<ul>
dimitri's avatar
dimitri committed
89
<li>Section \ref features presents an overview of what doxygen can do.
mueller's avatar
mueller committed
90
<li>Section \ref history shows what has changed during the development 
dimitri's avatar
dimitri committed
91
                 of doxygen and what still has to be done.
mueller's avatar
mueller committed
92 93
<li>Section \ref doxygen_usage shows how to use the \c doxygen program.
<li>Section \ref doxytag_usage shows how to use the \c doxytag program.
dimitri's avatar
dimitri committed
94
<li>Section \ref doxywizard_usage shows how to use the \c doxywizard program. 
mueller's avatar
mueller committed
95
<li>Section \ref installdox_usage shows how to use the \c installdox
dimitri's avatar
dimitri committed
96
                 script that is generated by doxygen if you use tag files. 
mueller's avatar
mueller committed
97 98 99 100 101 102
<li>Section \ref config shows how to fine-tune doxygen, so it 
              generates the documentation you want.
<li>Section \ref commands shows an overview of the special commands that can be 
              used within the documentation.
<li>Section \ref htmlcmds shows an overview of the HTML commands that
              can be used within the documentation.
dimitri's avatar
dimitri committed
103
<li>Section \ref xmlcmds shows an overview of the C# style XML commands that
dimitri's avatar
dimitri committed
104
              can be used within the documentation.
dimitri's avatar
dimitri committed
105 106 107 108 109 110 111
</ul>

The third part provides information for developers:

<ul>
<li>Section \ref arch gives a global overview of how doxygen is internally
    structured.
dimitri's avatar
dimitri committed
112
<li>Section \ref perlmod shows how to use the PerlMod output.
mueller's avatar
mueller committed
113 114
<li>Section \ref langhowto explains how to add support for new
              output languages.
mueller's avatar
mueller committed
115 116
</ul>

dimitri's avatar
dimitri committed
117
\n<h2>Doxygen license</h2>
dimitri's avatar
dimitri committed
118 119 120
\addindex license
\addindex GPL

dimitri's avatar
dimitri committed
121
Copyright &copy; 1997-2009 by 
dimitri's avatar
dimitri committed
122 123 124 125 126 127 128
<a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>.<p>

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 
dimitri's avatar
dimitri committed
129
<a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">
dimitri's avatar
dimitri committed
130 131 132 133 134 135
GNU General Public License</a>
for more details.
<p>
Documents produced by doxygen are derivative works derived from the
input used in their production; they are not affected by this license.

dimitri's avatar
dimitri committed
136
<h2>User examples</h2>
mueller's avatar
mueller committed
137

dimitri's avatar
dimitri committed
138 139 140 141 142 143 144 145 146 147 148
Doxygen supports a number of \ref output "output formats" where HTML is the
most popular one. I've gathered 
\htmlonly
<a href="http://www.doxygen.org/results.html">some nice examples</a> 
\endhtmlonly
\latexonly
some nice examples (see {\tt http://www.doxygen.org/results.html})
\endlatexonly
of real-life projects using doxygen.

These are part of a larger
mueller's avatar
mueller committed
149
\htmlonly
dimitri's avatar
dimitri committed
150
<a href="http://www.doxygen.org/projects.html">list of projects</a> 
dimitri's avatar
dimitri committed
151
that use doxygen.
mueller's avatar
mueller committed
152 153
\endhtmlonly
\latexonly
dimitri's avatar
dimitri committed
154
list of projects that use doxygen (see {\tt http://www.doxygen.org/projects.html}).
mueller's avatar
mueller committed
155
\endlatexonly
dimitri's avatar
dimitri committed
156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172
If you know other projects, let <a href="mailto:dimitri@stack.nl?subject=New%20project%20using%20Doxygen">me</a> 
know and I'll add them. 

<h2>Commercial Support</h2>

I'm currently investigating the possibilities of providing
commercial support for doxygen. The forms of support I'm thinking of
are: 
<ul>
<li>implementing features, 
<li>fixing bugs, 
<li>providing priority help in answering questions. 
</ul>
To get a better understanding of the feasibility,
please let <a href="mailto:dimitri@stack.nl?subject=Doxygen%20Commercial%20Support">me</a> know if you 
have a need for this type (or another type)
of doxygen related commercial support.
mueller's avatar
mueller committed
173

mueller's avatar
mueller committed
174
<h2>Future work</h2>
dimitri's avatar
dimitri committed
175 176 177 178 179 180
Although doxygen is successfully used by large number of companies and 
open source projects already, there is always room for improvement. 
<p>
You can submit enhancement requests in
<a href="https://bugzilla.gnome.org/buglist.cgi?product=doxygen&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_severity=enhancement">the bug tracker</a>.
Make sure the severity of the bug report is set to "enhancement".
mueller's avatar
mueller committed
181

mueller's avatar
mueller committed
182 183 184 185
<h2>Acknowledgements</h2>
\addindex acknowledgements
Thanks go to:
<ul>
dimitri's avatar
dimitri committed
186 187
<li>\addindex Doc++
    Malte Z&ouml;ckler and Roland Wunderling, authors of DOC++.
dimitri's avatar
dimitri committed
188
    The first version of doxygen borrowed some code of an old version of DOC++. 
mueller's avatar
mueller committed
189
    Although I have rewritten practically all code since then, DOC++ has still 
dimitri's avatar
dimitri committed
190
    given me a good start in writing doxygen.
dimitri's avatar
dimitri committed
191
<li>All people at Qt Software, for creating a beautiful GUI Toolkit
dimitri's avatar
dimitri committed
192
    (which is very useful as a Windows/Unix platform abstraction layer :-)
dimitri's avatar
dimitri committed
193
<li>My brother Frank
mueller's avatar
mueller committed
194
    for rendering the logos.
mueller's avatar
mueller committed
195
<li>Harm van der Heijden for adding HTML help support.
dimitri's avatar
dimitri committed
196 197 198
<li>Wouter Slegers of 
    <a href="http://www.yourcreativesolutions.nl">Your Creative Solutions</a> 
    for registering the www.doxygen.org domain.
dimitri's avatar
dimitri committed
199
<li>Parker Waechter for adding the RTF output generator.
dimitri's avatar
dimitri committed
200 201
<li>Joerg Baumann, for adding conditional documentation blocks, 
    PDF links, and the configuration generator.
dimitri's avatar
dimitri committed
202
<li>Tim Mensch for adding the todo command.
dimitri's avatar
dimitri committed
203
<li>Christian Hammond for redesigning the web-site.
dimitri's avatar
dimitri committed
204
<li>Ken Wong for providing the HTML tree view code.
dimitri's avatar
dimitri committed
205
<li>Talin for adding support for C# style comments with XML markup.
dimitri's avatar
dimitri committed
206 207
<li>Petr Prikryl for coordinating the internationalisation support.
    All language maintainers for providing translations into many languages.
dimitri's avatar
dimitri committed
208 209
<li>The band <a href="http://www.porcupinetree.com">Porcupine Tree</a> for 
    providing hours of great music to listen to while coding.
dimitri's avatar
dimitri committed
210
<li>many, many others for suggestions, patches and bug reports.
mueller's avatar
mueller committed
211 212 213
</ul>
*/