|
1 /****************************************************************************** |
|
2 * |
|
3 * |
|
4 * |
|
5 * Copyright (C) 1997-2008 by Dimitri van Heesch. |
|
6 * |
|
7 * Permission to use, copy, modify, and distribute this software and its |
|
8 * documentation under the terms of the GNU General Public License is hereby |
|
9 * granted. No representations are made about the suitability of this software |
|
10 * for any purpose. It is provided "as is" without express or implied warranty. |
|
11 * See the GNU General Public License for more details. |
|
12 * |
|
13 * Documents produced by Doxygen are derivative works derived from the |
|
14 * input used in their production; they are not affected by this license. |
|
15 * |
|
16 */ |
|
17 /*! \page index |
|
18 \if logo_on |
|
19 <center> |
|
20 \htmlonly |
|
21 <img src="doxygen_logo.gif" width="634" height="197" alt="doxygen"/><br/> |
|
22 Version: $(VERSION) |
|
23 \endhtmlonly |
|
24 </center> |
|
25 \endif |
|
26 |
|
27 <h2>Introduction</h2> |
|
28 Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL |
|
29 (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D. |
|
30 |
|
31 It can help you in three ways: |
|
32 <ol> |
|
33 <li> It can generate an on-line documentation browser (in HTML) and/or an |
|
34 off-line reference manual (in \f$\mbox{\LaTeX}\f$) from a set |
|
35 of documented source files. |
|
36 There is also support for generating output in RTF (MS-Word), |
|
37 PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. |
|
38 The documentation is extracted directly from the sources, which |
|
39 makes it much easier to keep the documentation consistent with the |
|
40 source code. |
|
41 <li> You can \ref extract_all "configure" doxygen to extract the code structure |
|
42 from undocumented source files. This is very useful to quickly |
|
43 find your way in large source distributions. |
|
44 You can also visualize the relations between the various elements |
|
45 by means of include dependency graphs, inheritance diagrams, |
|
46 and collaboration diagrams, which are all generated automatically. |
|
47 <li> You can even `abuse' doxygen for creating normal documentation (as I did |
|
48 for this manual). |
|
49 </ol> |
|
50 |
|
51 Doxygen is developed under <a href="http://www.linux.org">Linux</a> |
|
52 and Mac OS X, but is set-up to be highly portable. As a result, it |
|
53 runs on most other Unix flavors as well. Furthermore, executables for |
|
54 Windows are available. |
|
55 |
|
56 \n This manual is divided into three parts, each of which is divided into several |
|
57 sections. |
|
58 |
|
59 The first part forms a user manual: |
|
60 <ul> |
|
61 <li>Section \ref install discusses how to |
|
62 <a href="http://www.doxygen.org/download.html">download</a>, compile and install |
|
63 doxygen for your platform. |
|
64 <li>Section \ref starting tells you how to generate your first piece of |
|
65 documentation quickly. |
|
66 <li>Section \ref docblocks demonstrates the various ways that code can |
|
67 be documented. |
|
68 <li>Section \ref lists show various ways to create lists. |
|
69 <li>Section \ref grouping shows how to group things together. |
|
70 <li>Section \ref formulas shows how to insert formulas in the documentation. |
|
71 <li>Section \ref diagrams describes the diagrams and graphs that doxygen can generate. |
|
72 <li>Section \ref preprocessing explains how doxygen deals with macro definitions. |
|
73 <li>Section \ref autolink shows how to put links to files, classes, |
|
74 and members in the documentation. |
|
75 <li>Section \ref output shows how to generate the various output formats |
|
76 supported by doxygen. |
|
77 <li>Section \ref searching shows various ways to search in the HTML documentation. |
|
78 <li>Section \ref customize explains how you can customize the output generated |
|
79 by doxygen. |
|
80 <li>Section \ref custcmd show how to define and use custom commands in your comments. |
|
81 <li>Section \ref external explains how to let doxygen create links to externally generated documentation. |
|
82 <li>Section \ref faq gives answers to frequently asked questions. |
|
83 <li>Section \ref trouble tells you what to do when you have problems. |
|
84 </ul> |
|
85 |
|
86 The second part forms a reference manual: |
|
87 |
|
88 <ul> |
|
89 <li>Section \ref features presents an overview of what doxygen can do. |
|
90 <li>Section \ref history shows what has changed during the development |
|
91 of doxygen and what still has to be done. |
|
92 <li>Section \ref doxygen_usage shows how to use the \c doxygen program. |
|
93 <li>Section \ref doxytag_usage shows how to use the \c doxytag program. |
|
94 <li>Section \ref doxywizard_usage shows how to use the \c doxywizard program. |
|
95 <li>Section \ref installdox_usage shows how to use the \c installdox |
|
96 script that is generated by doxygen if you use tag files. |
|
97 <li>Section \ref config shows how to fine-tune doxygen, so it |
|
98 generates the documentation you want. |
|
99 <li>Section \ref commands shows an overview of the special commands that can be |
|
100 used within the documentation. |
|
101 <li>Section \ref htmlcmds shows an overview of the HTML commands that |
|
102 can be used within the documentation. |
|
103 <li>Section \ref xmlcmds shows an overview of the C# style XML commands that |
|
104 can be used within the documentation. |
|
105 </ul> |
|
106 |
|
107 The third part provides information for developers: |
|
108 |
|
109 <ul> |
|
110 <li>Section \ref arch gives a global overview of how doxygen is internally |
|
111 structured. |
|
112 <li>Section \ref perlmod shows how to use the PerlMod output. |
|
113 <li>Section \ref langhowto explains how to add support for new |
|
114 output languages. |
|
115 </ul> |
|
116 |
|
117 \n<h2>Doxygen license</h2> |
|
118 \addindex license |
|
119 \addindex GPL |
|
120 |
|
121 Copyright © 1997-2009 by |
|
122 <a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>.<p> |
|
123 |
|
124 Permission to use, copy, modify, and distribute this software and its |
|
125 documentation under the terms of the GNU General Public License is hereby |
|
126 granted. No representations are made about the suitability of this software |
|
127 for any purpose. It is provided "as is" without express or implied warranty. |
|
128 See the |
|
129 <a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html"> |
|
130 GNU General Public License</a> |
|
131 for more details. |
|
132 <p> |
|
133 Documents produced by doxygen are derivative works derived from the |
|
134 input used in their production; they are not affected by this license. |
|
135 |
|
136 <h2>User examples</h2> |
|
137 |
|
138 Doxygen supports a number of \ref output "output formats" where HTML is the |
|
139 most popular one. I've gathered |
|
140 \htmlonly |
|
141 <a href="http://www.doxygen.org/results.html">some nice examples</a> |
|
142 \endhtmlonly |
|
143 \latexonly |
|
144 some nice examples (see {\tt http://www.doxygen.org/results.html}) |
|
145 \endlatexonly |
|
146 of real-life projects using doxygen. |
|
147 |
|
148 These are part of a larger |
|
149 \htmlonly |
|
150 <a href="http://www.doxygen.org/projects.html">list of projects</a> |
|
151 that use doxygen. |
|
152 \endhtmlonly |
|
153 \latexonly |
|
154 list of projects that use doxygen (see {\tt http://www.doxygen.org/projects.html}). |
|
155 \endlatexonly |
|
156 If you know other projects, let <a href="mailto:dimitri@stack.nl?subject=New%20project%20using%20Doxygen">me</a> |
|
157 know and I'll add them. |
|
158 |
|
159 <h2>Commercial Support</h2> |
|
160 |
|
161 I'm currently investigating the possibilities of providing |
|
162 commercial support for doxygen. The forms of support I'm thinking of |
|
163 are: |
|
164 <ul> |
|
165 <li>implementing features, |
|
166 <li>fixing bugs, |
|
167 <li>providing priority help in answering questions. |
|
168 </ul> |
|
169 To get a better understanding of the feasibility, |
|
170 please let <a href="mailto:dimitri@stack.nl?subject=Doxygen%20Commercial%20Support">me</a> know if you |
|
171 have a need for this type (or another type) |
|
172 of doxygen related commercial support. |
|
173 |
|
174 <h2>Future work</h2> |
|
175 Although doxygen is successfully used by large number of companies and |
|
176 open source projects already, there is always room for improvement. |
|
177 <p> |
|
178 You can submit enhancement requests in |
|
179 <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>. |
|
180 Make sure the severity of the bug report is set to "enhancement". |
|
181 |
|
182 <h2>Acknowledgements</h2> |
|
183 \addindex acknowledgements |
|
184 Thanks go to: |
|
185 <ul> |
|
186 <li>\addindex Doc++ |
|
187 Malte Zöckler and Roland Wunderling, authors of DOC++. |
|
188 The first version of doxygen borrowed some code of an old version of DOC++. |
|
189 Although I have rewritten practically all code since then, DOC++ has still |
|
190 given me a good start in writing doxygen. |
|
191 <li>All people at Qt Software, for creating a beautiful GUI Toolkit |
|
192 (which is very useful as a Windows/Unix platform abstraction layer :-) |
|
193 <li>My brother Frank |
|
194 for rendering the logos. |
|
195 <li>Harm van der Heijden for adding HTML help support. |
|
196 <li>Wouter Slegers of |
|
197 <a href="http://www.yourcreativesolutions.nl">Your Creative Solutions</a> |
|
198 for registering the www.doxygen.org domain. |
|
199 <li>Parker Waechter for adding the RTF output generator. |
|
200 <li>Joerg Baumann, for adding conditional documentation blocks, |
|
201 PDF links, and the configuration generator. |
|
202 <li>Tim Mensch for adding the todo command. |
|
203 <li>Christian Hammond for redesigning the web-site. |
|
204 <li>Ken Wong for providing the HTML tree view code. |
|
205 <li>Talin for adding support for C# style comments with XML markup. |
|
206 <li>Petr Prikryl for coordinating the internationalisation support. |
|
207 All language maintainers for providing translations into many languages. |
|
208 <li>The band <a href="http://www.porcupinetree.com">Porcupine Tree</a> for |
|
209 providing hours of great music to listen to while coding. |
|
210 <li>many, many others for suggestions, patches and bug reports. |
|
211 </ul> |
|
212 */ |
|
213 |