diff options
Diffstat (limited to 'doc/starting.doc')
| -rw-r--r-- | doc/starting.doc | 328 |
1 files changed, 328 insertions, 0 deletions
diff --git a/doc/starting.doc b/doc/starting.doc new file mode 100644 index 0000000..4e5481e --- /dev/null +++ b/doc/starting.doc @@ -0,0 +1,328 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2012 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. + * + * Documents produced by Doxygen are derivative works derived from the + * input used in their production; they are not affected by this license. + * + */ +/*! \page starting Getting started +\tableofcontents + +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. + +Optionally, the executable \c doxywizard can be used, which is a +\ref doxywizard_usage "graphical front-end" for editing the configuration file +that is used by doxygen and for running doxygen in a graphical environment. +For Mac OS X doxywizard will be started by clicking on the Doxygen application +icon. + +The following figure shows the relation between the tools and the flow +of information between them (it looks complex but that's only because it +tries to be complete): + +\image html infoflow.png "Doxygen information flow" +\image latex infoflow.eps "Doxygen information flow" width=14cm + +\section step0 Step 0: Check if doxygen supports your programming language + +First, assure that your programming language has a reasonable chance of being +recognized by Doxygen. These languages are supported by default: C, C++, C#, +Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, and D. It +is possible to configure certain file type extensions to use certain parsers: +see the \ref cfg_extension_mapping "Configuration/ExtensionMappings" for details. +Also, completely different languages can be supported by using preprocessor +programs: see the <a href="http://www.doxygen.org/helpers.html">Helpers page</a> +for details. + +\section 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 +from the command line 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. +If you use <code>-</code> (i.e. the minus sign) as the file name then +doxygen will try to read the configuration file from standard +input (<code>stdin</code>), which can be useful for scripting. + +The configuration file has a format that is similar to that of a (simple) +Makefile. It consists 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 in a generated template +configuration file to their default value. See section \ref config for +more details about the configuration file. + +If you do not wish to edit the config file with a text editor, you should +have a look at \ref doxywizard_usage "doxywizard", which is a GUI +front-end that can create, read and write doxygen configuration files, +and allows setting configuration options by entering them via dialogs. + +For a small project consisting of a few C and/or C++ source +and header files, you can leave +\ref cfg_input "INPUT" tag empty and doxygen will search for sources in +the current directory. + +If you have a larger project consisting of a source directory or tree +you should assign the root directory or +directories to the \ref cfg_input "INPUT" tag, and add one or more file +patterns to the \ref cfg_file_patterns "FILE_PATTERNS" tag +(for instance `*.cpp *.h`). Only files that match one of the +patterns will be parsed (if the patterns are omitted a list of +typical patterns is used for the types of files doxygen supports). +For recursive parsing of a source tree you must set +the \ref cfg_recursive "RECURSIVE" tag to \c YES. To further fine-tune the +list of files that is parsed the \ref cfg_exclude "EXCLUDE" and +\ref cfg_exclude_patterns "EXCLUDE_PATTERNS" tags can be used. +To omit all \c test directories from a source tree for instance, one could use: + +\verbatim EXCLUDE_PATTERNS = */test/* +\endverbatim + +Doxygen looks at the file's extension to determine how to parse a file, +using the following table: + +Extension | Language +---------:|--------- +.idl |IDL +.ddl |IDL +.odl |IDL +.java |Java +.cs |C# +.d |D +.php |PHP +.php4 |PHP +.php5 |PHP +.inc |PHP +.phtml |PHP +.m |Objective-C +.M |Objective-C +.mm |Objective-C +.py |Python +.f |Fortran +.for |Fortran +.f90 |Fortran +.vhd |VHDL +.vhdl |VHDL +.tcl |TCL +.ucf |VHDL +.qsf |VHDL +.md |Markdown +.markdown |Markdown + +Any other extension is parsed as if it is a C/C++ file. + +\anchor extract_all +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 structure is and how the documented result would look like. +To do so, you must set +the \ref cfg_extract_all "EXTRACT_ALL" tag in the configuration file +to \c YES. Then, doxygen will pretend everything in your sources is documented. +Please note that as a consequence warnings about undocumented members +will not be generated as long as \ref cfg_extract_all "EXTRACT_ALL" is +set to \c YES. + +To analyze an existing piece of software it is useful to cross-reference +a (documented) entity with its definition in the source files. Doxygen will +generate such cross-references if you set +the \ref cfg_source_browser "SOURCE_BROWSER" tag to \c YES. +It can also include the sources directly into the documentation by setting +\ref cfg_inline_sources "INLINE_SOURCES" to \c YES (this can be handy for +code reviews for instance). + +\section step2 Step 2: Running doxygen + +To generate the documentation you can now enter: +\verbatim +doxygen <config-file> +\endverbatim + +Depending on your settings doxygen will create \c html, \c rtf, +\c latex, \c xml and/or \c man directories inside the output directory. +As the names suggest these directories contain the +generated documentation in HTML, RTF, \f$\mbox{\LaTeX}\f$, XML and +Unix-Man page format. + +The default output directory is the directory in which \c doxygen +is started. The root directory to which the output is written can be changed +using the \ref cfg_output_directory "OUTPUT_DIRECTORY". The format specific +directory within the output directory can be selected using the +\ref cfg_html_output "HTML_OUTPUT", \ref cfg_rtf_output "RTF_OUTPUT", +\ref cfg_latex_output "LATEX_OUTPUT", \ref cfg_xml_output "XML_OUTPUT", +and \ref cfg_man_output "MAN_OUTPUT" +tags of the configuration file. If the output directory does not exist, +\c doxygen will try to create it for you (but it will \e not try to create +a whole path recursively, like <code>mkdir -p</code> does). + +\subsection html_out HTML output +\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 using Mozilla Firefox, Google Chrome, Safari, and sometimes +IE8, IE9, and Opera to test the generated output). + +Some of the features the HTML section (such as +\ref cfg_generate_treeview "GENERATE_TREEVIEW" or the search engine) +require a browser that supports Dynamic HTML and Javascript enabled. + +\subsection latex_out LaTeX output +\addindex LaTeX +The generated \f$\mbox{\LaTeX}\f$ documentation must first be compiled by +a \f$\mbox{\LaTeX}\f$ compiler (I use a recent teTeX distribution for Linux +and MacOSX and MikTex for Windows). +To simplify the process of compiling the generated +documentation, \c doxygen writes a \c Makefile into the \c latex directory +(on the Windows platform also a \c make.bat batch file is generated). + +The contents and targets in the \c Makefile depend on the setting of +\ref cfg_use_pdflatex "USE_PDFLATEX". If it is disabled (set to \c NO), then +typing \c make in the \c latex directory a \c dvi file called \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 `make ps` (this requires `dvips`). + +To put 2 pages on one physical page use `make ps_2on1` instead. +The resulting 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. + +Conversion to PDF is also possible if you have installed the ghostscript +interpreter; just type `make pdf` (or `make pdf_2on1`). + +To get the best results for PDF output you should set +the \ref cfg_pdf_hyperlinks "PDF_HYPERLINKS" +and \ref cfg_use_pdflatex "USE_PDFLATEX" tags to \c YES. +In this case the \c Makefile will only contain a target to build +\c refman.pdf directly. + +\subsection rtf_out RTF output +\addindex RTF +Doxygen combines the RTF output to a single file called refman.rtf. This +file is optimized for importing into the Microsoft Word. Certain information +is encoded using so called fields. To show the actual value you need to +select all (Edit - select all) and then toggle fields (right click and select +the option from the drop down menu). + +\subsection xml_out XML output +\addindex XML +The XML output consists of a structured "dump" of the information gathered +by doxygen. Each compound (class/namespace/file/...) has its own XML file +and there is also an index file called `index.xml`. + +A file called `combine.xslt` +XSLT script is also generated and can be used to combine all XML files +into a single file. + +Doxygen also generates two XML schema files `index.xsd` +(for the index file) and `compound.xsd` (for the compound files). +This schema file describes the possible elements, their attributes and +how they are structured, i.e. it the describes the grammar of the XML +files and can be used for validation or to steer XSLT scripts. + +In the `addon/doxmlparser` directory you can find a parser library for reading +the XML output produced by doxygen in an incremental way +(see `addon/doxmlparser/include/doxmlintf.h` for the interface of the library) + +\subsection man_out Man page output +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 \c MANPATH +environment variable). Note 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. + +\section step3 Step 3: Documenting the sources + +Although documenting the sources is presented as step 3, in a new project +this should of course 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 and some related design +documentation as well. + +If the \ref cfg_extract_all "EXTRACT_ALL" option is set to \c NO in the +configuration file (the default), then doxygen will only generate +documentation for \e documented entities. So +how do you document these? For members, classes and namespaces there are +basically two options: +1. 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 documentation directly after the + member. + + See section \ref specialblock to learn more about special + documentation blocks. +2. 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 entity that can be documented (e.g. a member, class, + namespace or file). + + See section \ref structuralcommands to learn more + about structural commands. + +The advantage of the first option is that you do not have to repeat the +name of the entity. + +Files can only be documented using the second option, since there is +no way to put a documentation block before a file. Of course, file members +(functions, variables, typedefs, defines) do not need an explicit +structural command; just putting a special documentation block in front or +behind them will work fine. + +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: +- Markdown formatting is replaced by corresponding HTML or special + commands. +- The special commands inside the documentation are executed. See + section \ref commands for an overview of all commands. +- If a line starts with some whitespace followed by one or more asterisks + (`*`) and then optionally more whitespace, + then all whitespace and asterisks are removed. +- 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. +- Links are created for words corresponding to documented classes + (unless the word is preceded by a \%; then the word will not be linked and + the \% sign is removed). +- 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. +- 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. + +\htmlonly +Go to the <a href="docblocks.html">next</a> section or return to the + <a href="index.html">index</a>. +\endhtmlonly + +*/ + |