|
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 starting Getting started |
|
18 |
|
19 The executable \c doxygen is the main program that parses the sources and |
|
20 generates the documentation. See section \ref doxygen_usage for more |
|
21 detailed usage information. |
|
22 |
|
23 The executable \c doxytag is only needed if you want to generate references |
|
24 to external documentation (i.e. documentation that was generated by doxygen) |
|
25 for which you do not have the sources. See section \ref doxytag_usage |
|
26 for more detailed usage information. |
|
27 |
|
28 Optionally, the executable \c doxywizard can be used, which is a |
|
29 \ref doxywizard_usage "graphical front-end" for editing the configuration file |
|
30 that is used by doxygen and for running doxygen in a graphical environment. |
|
31 For Mac OS X doxywizard will be started by clicking on the Doxygen application |
|
32 icon. |
|
33 |
|
34 The following figure shows the relation between the tools and the flow |
|
35 of information between them (it looks complex but that's only because it |
|
36 tries to be complete): |
|
37 |
|
38 \image html infoflow.gif "Doxygen information flow" |
|
39 \image latex infoflow.eps "Doxygen information flow" width=14cm |
|
40 |
|
41 \section step1 Step 1: Creating a configuration file |
|
42 |
|
43 Doxygen uses a configuration file to determine all of its settings. |
|
44 Each project should get its own configuration file. A project can consist |
|
45 of a single source file, but can also be an entire source tree that is |
|
46 recursively scanned. |
|
47 |
|
48 To simplify the creation of a configuration file, doxygen can create a |
|
49 template configuration file for you. To do this call \c doxygen |
|
50 from the command line with the \c -g option: |
|
51 \verbatim |
|
52 doxygen -g <config-file> |
|
53 \endverbatim |
|
54 |
|
55 where \<config-file\> is the name of the configuration file. If you omit |
|
56 the file name, a file named \c Doxyfile will be created. If a file with the |
|
57 name \<config-file\> already exists, doxygen will rename it to |
|
58 \<config-file\>.bak before generating the configuration template. |
|
59 If you use <code>-</code> (i.e. the minus sign) as the file name then |
|
60 doxygen will try to read the configuration file from standard |
|
61 input (<code>stdin</code>), which can be useful for scripting. |
|
62 |
|
63 The configuration file has a format that is similar to that of a (simple) |
|
64 Makefile. It consists of a number of assignments (tags) of the form: |
|
65 |
|
66 <tt>TAGNAME = VALUE</tt> or <br> |
|
67 <tt>TAGNAME = VALUE1 VALUE2 ... </tt><br> |
|
68 |
|
69 You can probably leave the values of most tags in a generated template |
|
70 configuration file to their default value. See section \ref config for |
|
71 more details about the configuration file. |
|
72 |
|
73 If you do not wish to edit the config file with a text editor, you should |
|
74 have a look at \ref doxywizard_usage "doxywizard", which is a GUI |
|
75 front-end that can create, read and write doxygen configuration files, |
|
76 and allows setting configuration options by entering them via dialogs. |
|
77 |
|
78 For a small project consisting of a few C and/or C++ source |
|
79 and header files, you can leave |
|
80 \ref cfg_input "INPUT" tag empty and doxygen will search for sources in |
|
81 the current directory. |
|
82 |
|
83 If you have a larger project consisting of a source directory or tree |
|
84 you should assign the root directory or |
|
85 directories to the \ref cfg_input "INPUT" tag, and add one or more file |
|
86 patterns to the \ref cfg_file_patterns "FILE_PATTERNS" tag |
|
87 (for instance <code>*.cpp *.h</code>). Only files that match one of the |
|
88 patterns will be parsed (if the patterns are omitted a list of |
|
89 source extensions is used). |
|
90 For recursive parsing of a source tree you must set |
|
91 the \ref cfg_recursive "RECURSIVE" tag to \c YES. To further fine-tune the |
|
92 list of files that is parsed the \ref cfg_exclude "EXCLUDE" and |
|
93 \ref cfg_exclude_patterns "EXCLUDE_PATTERNS" tags can be used. |
|
94 To omit all \c test directories from a source tree for instance, one could use: |
|
95 \verbatim EXCLUDE_PATTERNS = */test/* |
|
96 \endverbatim |
|
97 |
|
98 Doxygen looks at the file's extension to determine how to parse a file. |
|
99 If a file has an <code>.idl</code> or <code>.odl</code> extension it is |
|
100 treated as an IDL file. If it has a <code>.java</code> extension it is |
|
101 treated as a file written in Java. Files ending with <code>.cs</code> are |
|
102 treated as C# files and the <code>.py</code> extension selects the |
|
103 Python parser. Finally, files with the extensions <code>.php</code>, <code>.php4</code>, |
|
104 <code>.inc</code> or <code>.phtml</code> are treated as PHP sources. |
|
105 Any other extension is parsed as if it is a C/C++ file, where files that |
|
106 end with <code>.m</code> are treated as Objective-C source files. |
|
107 |
|
108 \anchor extract_all |
|
109 If you start using doxygen for an existing project (thus without any |
|
110 documentation that doxygen is aware of), you can still get an idea of |
|
111 what the structure is and how the documented result would look like. |
|
112 To do so, you must set |
|
113 the \ref cfg_extract_all "EXTRACT_ALL" tag in the configuration file |
|
114 to \c YES. Then, doxygen will pretend everything in your sources is documented. |
|
115 Please note that as a consequence warnings about undocumented members |
|
116 will not be generated as long as \ref cfg_extract_all "EXTRACT_ALL" is |
|
117 set to \c YES. |
|
118 |
|
119 To analyse an existing piece of software it is useful to cross-reference |
|
120 a (documented) entity with its definition in the source files. Doxygen will |
|
121 generate such cross-references if you set |
|
122 the \ref cfg_source_browser "SOURCE_BROWSER" tag to \c YES. |
|
123 It can also include the sources directly into the documentation by setting |
|
124 \ref cfg_inline_sources "INLINE_SOURCES" to \c YES (this can be handy for |
|
125 code reviews for instance). |
|
126 |
|
127 \section step2 Step 2: Running doxygen |
|
128 |
|
129 To generate the documentation you can now enter: |
|
130 \verbatim |
|
131 doxygen <config-file> |
|
132 \endverbatim |
|
133 |
|
134 Depending on your settings doxygen will create \c html, \c rtf, |
|
135 \c latex, \c xml and/or \c man directories inside the output directory. |
|
136 As the names suggest these directories contain the |
|
137 generated documentation in HTML, RTF, \f$\mbox{\LaTeX}\f$, XML and |
|
138 Unix-Man page format. |
|
139 |
|
140 The default output directory is the directory in which \c doxygen |
|
141 is started. The root directory to which the output is written can be changed |
|
142 using the \ref cfg_output_directory "OUTPUT_DIRECTORY". The format specific |
|
143 directory within the output directory can be selected using the |
|
144 \ref cfg_html_output "HTML_OUTPUT", \ref cfg_rtf_output "RTF_OUTPUT", |
|
145 \ref cfg_latex_output "LATEX_OUTPUT", \ref cfg_xml_output "XML_OUTPUT", |
|
146 and \ref cfg_man_output "MAN_OUTPUT" |
|
147 tags of the configuration file. If the output directory does not exist, |
|
148 \c doxygen will try to create it for you (but it will \e not try to create |
|
149 a whole path recursively, like <code>mkdir -p</code> does). |
|
150 |
|
151 \subsection html_out HTML output |
|
152 \addindex browser |
|
153 The generated HTML documentation can be viewed by pointing a HTML browser |
|
154 to the \c index.html file in the \c html directory. For the best results |
|
155 a browser that supports cascading style sheets (CSS) should be used |
|
156 (I'm using Mozilla, Safari, Konqueror, and sometimes IE6 to test the |
|
157 generated output). |
|
158 |
|
159 Some of the features the HTML section (such as |
|
160 \ref cfg_generate_treeview "GENERATE_TREEVIEW" or the search engine) |
|
161 require a browser that supports DHTML and Javascript. |
|
162 |
|
163 \subsection latex_out LaTeX output |
|
164 \addindex LaTeX |
|
165 The generated \f$\mbox{\LaTeX}\f$ documentation must first be compiled by |
|
166 a \f$\mbox{\LaTeX}\f$ compiler (I use a recent teTeX distribution). |
|
167 To simplify the process of compiling the generated |
|
168 documentation, \c doxygen writes a \c Makefile into the \c latex directory. |
|
169 |
|
170 The contents and targets in the \c Makefile depend on the setting of |
|
171 \ref cfg_use_pdflatex "USE_PDFLATEX". If it is disabled (set to \c NO), then |
|
172 typing \c make in the \c latex directory a dvi file called \c refman.dvi |
|
173 will be generated. This file can then be viewed using \c xdvi or |
|
174 converted into a PostScript file \c refman.ps by |
|
175 typing <code>make ps</code> (this requires <code>dvips</code>). |
|
176 |
|
177 To put 2 pages on one physical page use <code>make ps_2on1</code> instead. |
|
178 The resulting PostScript file can be send to a PostScript |
|
179 printer. If you do not have a PostScript printer, you can try to use |
|
180 ghostscript to convert PostScript into something your printer understands. |
|
181 |
|
182 Conversion to PDF is also possible if you have installed the ghostscript |
|
183 interpreter; just type <code>make pdf</code> (or <code>make pdf_2on1</code>). |
|
184 |
|
185 To get the best results for PDF output you should set |
|
186 the \ref cfg_pdf_hyperlinks "PDF_HYPERLINKS" |
|
187 and \ref cfg_use_pdflatex "USE_PDFLATEX" tags to \c YES. |
|
188 In this case the \c Makefile will only contain a target to build |
|
189 \c refman.pdf directly. |
|
190 |
|
191 \subsection rtf_out RTF output |
|
192 \addindex RTF |
|
193 Doxygen combines the RTF output to a single file called refman.rtf. This |
|
194 file is optimized for importing into the Microsoft Word. Certain information |
|
195 is encoded using field. To show the actual value you need to |
|
196 select all (Edit - select all) and then toggle fields (right click and select |
|
197 the option from the drop down menu). |
|
198 |
|
199 \subsection xml_out XML output |
|
200 \addindex XML |
|
201 The XML output consists of a structured "dump" of the information gathered |
|
202 by doxygen. Each compound (class/namespace/file/...) has its own XML file |
|
203 and there is also an index file called index.xml. |
|
204 |
|
205 A file called combine.xslt |
|
206 XSLT script is also generated and can be used to combine all XML files |
|
207 into a single file. |
|
208 |
|
209 Doxygen also generates two XML schema files index.xsd |
|
210 (for the index file) and compound.xsd (for the compound files). |
|
211 This schema file describes the possible elements, their attributes and |
|
212 how they are structured, i.e. it the describes the grammar of the XML |
|
213 files and can be used for validation or to steer XSLT scripts. |
|
214 |
|
215 In the addon/doxmlparser directory you can find a parser library for reading |
|
216 the XML output produced by doxygen in an incremental way |
|
217 (see addon/doxmlparser/include/doxmlintf.h for the interface of the library) |
|
218 |
|
219 \subsection man_out Man page output |
|
220 The generated man pages can be viewed using the \c man program. You do need |
|
221 to make sure the man directory is in the man path (see the \c MANPATH |
|
222 environment variable). Note that there are some limitations to the |
|
223 capabilities of the man page format, so some information |
|
224 (like class diagrams, cross references and formulas) will be lost. |
|
225 |
|
226 \section step3 Step 3: Documenting the sources |
|
227 |
|
228 Although documenting the sources is presented as step 3, in a new project |
|
229 this should of course be step 1. Here I assume |
|
230 you already have some code and you want doxygen to generate a nice document |
|
231 describing the API and maybe the internals as well. |
|
232 |
|
233 If the \ref cfg_extract_all "EXTRACT_ALL" option is set to \c NO in the |
|
234 configuration file (the default), then doxygen will only generate |
|
235 documentation for \e documented members, files, classes and namespaces. So |
|
236 how do you document these? For members, classes and namespaces there are |
|
237 basically two options: |
|
238 <ol> |
|
239 <li>Place a \e special documentation block in front of the declaration or |
|
240 definition of the member, class or namespace. For file, class and namespace |
|
241 members it is also allowed to place the documention directly after the |
|
242 member. See section \ref specialblock to learn more about special |
|
243 documentation blocks. |
|
244 <li>Place a special documentation block somewhere else (another file or |
|
245 another location) \e and put a <em>structural command</em> in the |
|
246 documentation block. A structural command links a documentation block |
|
247 to a certain entity that can be documented (e.g. a member, class, |
|
248 namespace or file). See section \ref structuralcommands to learn more |
|
249 about structural commands. |
|
250 </ol> |
|
251 Files can only be documented using the second option, since there is |
|
252 no way to put a documentation block before a file. Of course, file members |
|
253 (functions, variable, typedefs, defines) do not need an explicit |
|
254 structural command; just putting a special documentation block in front or |
|
255 behind them will do. |
|
256 |
|
257 The text inside a special documentation block is parsed |
|
258 before it is written to the HTML and/or \f$\mbox{\LaTeX}\f$ output files. |
|
259 |
|
260 \addindex parsing |
|
261 During parsing the following steps take place: |
|
262 <ul> |
|
263 <li> The special commands inside the documentation are executed. See |
|
264 section \ref commands for an overview of all commands. |
|
265 <li> If a line starts with some whitespace followed by one or more asterisks |
|
266 (<tt>*</tt>) and then optionally more whitespace, |
|
267 then all whitespace and asterisks are removed. |
|
268 <li> All resulting blank lines are treated as a paragraph separators. |
|
269 This saves you from placing new-paragraph commands yourself |
|
270 in order to make the generated documentation readable. |
|
271 <li> Links are created for words corresponding to documented classes |
|
272 (unless the word is preceded by a \%; then the word will not be linked and |
|
273 the \% sign is removed). |
|
274 <li> Links to members are created when certain patterns are found in the |
|
275 text. See section \ref autolink |
|
276 for more information on how the automatic link generation works. |
|
277 <li> HTML tags that are in the documentation are interpreted and converted |
|
278 to \f$\mbox{\LaTeX}\f$ equivalents for the \f$\mbox{\LaTeX}\f$ output. |
|
279 See section \ref htmlcmds for an overview of all supported HTML tags. |
|
280 </ul> |
|
281 |
|
282 \htmlonly |
|
283 Go to the <a href="docblocks.html">next</a> section or return to the |
|
284 <a href="index.html">index</a>. |
|
285 \endhtmlonly |
|
286 |
|
287 */ |
|
288 |