mirror of https://gitee.com/openkylin/doxygen.git
197 lines
8.4 KiB
Plaintext
197 lines
8.4 KiB
Plaintext
/******************************************************************************
|
|
*
|
|
*
|
|
*
|
|
* Copyright (C) 1997-2015 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.
|
|
*
|
|
*/
|
|
/*!
|
|
\mainpage
|
|
<!--Doxygen Manual-->
|
|
\if logo_on
|
|
<center>
|
|
\htmlonly
|
|
<img src="doxygen_logo.svg" width="634" height="197" alt="doxygen"/><br/>
|
|
Version: $(VERSION)
|
|
\endhtmlonly
|
|
</center>
|
|
\endif
|
|
|
|
<h2>Introduction</h2>
|
|
Doxygen is the de facto standard tool for generating documentation from
|
|
annotated C++ sources, but it also supports other popular programming
|
|
languages such as C, Objective-C, C#, PHP, Java, Python, IDL
|
|
(Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, and to some extent D.
|
|
Doxygen also supports the hardware description language VHDL.
|
|
|
|
Doxygen 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 \LaTeX) from a set
|
|
of documented source files.
|
|
There is also support for generating output in RTF (MS-Word),
|
|
PostScript, hyperlinked PDF, compressed HTML, and Unix man pages.
|
|
The documentation is extracted directly from the sources, which
|
|
makes it much easier to keep the documentation consistent with the
|
|
source code.
|
|
<li> You can \ref extract_all "configure" doxygen to extract the code structure
|
|
from undocumented source files. This is very useful to quickly
|
|
find your way in large source distributions.
|
|
Doxygen can also visualize the relations between the various elements
|
|
by means of include dependency graphs, inheritance diagrams,
|
|
and collaboration diagrams, which are all generated automatically.
|
|
<li> You can also use doxygen for creating normal documentation (as I did
|
|
for the doxygen user manual and web-site).
|
|
</ol>
|
|
|
|
Doxygen is developed under Mac OS X and Linux, 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.
|
|
|
|
\n
|
|
This manual is divided into three parts, each of which is divided into several sections.
|
|
|
|
The first part forms a user manual:
|
|
<ul>
|
|
<li>Section \ref install discusses how to
|
|
<a href="https://www.doxygen.org/download.html">download</a>, compile and install
|
|
doxygen for your platform.
|
|
<li>Section \ref starting tells you how to generate your first piece of
|
|
documentation quickly.
|
|
<li>Section \ref docblocks demonstrates the various ways that code can
|
|
be documented.
|
|
<li>Section \ref markdown show the Markdown formatting supported by doxygen.
|
|
<li>Section \ref lists shows how to create lists.
|
|
<li>Section \ref grouping shows how to group things together.
|
|
<li>Section \ref tables shows how to insert tables in the documentation.
|
|
<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.
|
|
<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.
|
|
<li>Section \ref searching shows various ways to search in the HTML documentation.
|
|
<li>Section \ref extsearch shows how use the external search and index tools
|
|
<li>Section \ref customize explains how you can customize the output generated
|
|
by doxygen.
|
|
<li>Section \ref custcmd show how to define and use custom commands in your comments.
|
|
<li>Section \ref external explains how to let doxygen create links to externally generated documentation.
|
|
<li>Section \ref faq gives answers to frequently asked questions.
|
|
<li>Section \ref trouble tells you what to do when you have problems.
|
|
</ul>
|
|
|
|
The second part forms a reference manual:
|
|
|
|
<ul>
|
|
<li>Section \ref features presents an overview of what doxygen can do.
|
|
<li>Section \ref doxygen_usage shows how to use the \c doxygen program.
|
|
<li>Section \ref doxywizard_usage shows how to use the \c doxywizard program.
|
|
<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.
|
|
<li>Section \ref xmlcmds shows an overview of the C# style XML commands that
|
|
can be used within the documentation.
|
|
<li>Section \ref emojisup shows an introduction how emoji can be used within
|
|
the documentation.
|
|
</ul>
|
|
|
|
The third part provides information for developers:
|
|
|
|
<ul>
|
|
<li>Section \ref arch gives a global overview of how doxygen is internally
|
|
structured.
|
|
<li>Section \ref perlmod shows how to use the PerlMod output.
|
|
<li>Section \ref langhowto explains how to add support for new
|
|
output languages.
|
|
</ul>
|
|
|
|
\n<h2>Doxygen license</h2>
|
|
\addindex license
|
|
\addindex GPL
|
|
|
|
Copyright © 1997-2019 by
|
|
<a href="mailto:doxygen@gmail.com">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
|
|
<a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">
|
|
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.
|
|
|
|
<h2>User examples</h2>
|
|
|
|
Doxygen supports a number of \ref output "output formats" where HTML is the
|
|
most popular one. I've gathered
|
|
<a href="https://www.doxygen.org/results.html">some nice examples</a>
|
|
of real-life projects using doxygen.
|
|
|
|
These are part of a larger
|
|
<a href="https://www.doxygen.org/projects.html">list of projects</a>
|
|
that use doxygen.
|
|
If you know other projects, let <a href="mailto:doxygen@gmail.com?subject=New%20project%20using%20Doxygen">me</a>
|
|
know and I'll add them.
|
|
|
|
<h2>Future work</h2>
|
|
Although doxygen is successfully used by large number of companies and
|
|
open source projects already, there is always room for improvement.
|
|
<p>
|
|
You can also submit enhancement requests in
|
|
<a href="https://github.com/doxygen/doxygen/issues">the bug tracker</a>.
|
|
|
|
<h2>Acknowledgments</h2>
|
|
\addindex acknowledgments
|
|
Thanks go to:
|
|
<ul>
|
|
<li>\addindex Doc++
|
|
Malte Zöckler and Roland Wunderling, authors of DOC++.
|
|
The first version of doxygen borrowed some code of an old version of DOC++.
|
|
Although I have rewritten practically all code since then, DOC++ has still
|
|
given me a good start in writing doxygen.
|
|
<li>All people at Qt Software, for creating a beautiful GUI Toolkit.
|
|
<li>Steffen Schümann for creating ghc::filesystem which is used by doxygen.
|
|
<li>Michael McTernan for creating mscgen which is now embedded in doxygen.
|
|
<li>My brother Frank
|
|
for rendering the logos.
|
|
<li>Harm van der Heijden for adding HTML help support.
|
|
<li>Wouter Slegers of
|
|
<a href="http://www.yourcreativesolutions.nl">Your Creative Solutions</a>
|
|
for registering the www.doxygen.org domain.
|
|
<li>Martin Kreis for adding VHDL support.
|
|
<li>Parker Waechter for adding the RTF output generator.
|
|
<li>Joerg Baumann, for adding conditional documentation blocks,
|
|
PDF links, and the configuration generator.
|
|
<li>Tim Mensch for adding the todo command.
|
|
<li>Christian Hammond for redesigning the web-site.
|
|
<li>Ken Wong for providing the HTML tree view code.
|
|
<li>Talin for adding support for C# style comments with XML markup.
|
|
<li>Petr Prikryl for coordinating the internationalization support.
|
|
All language maintainers for providing translations into many languages.
|
|
<li>many, many others for suggestions, patches and bug reports.
|
|
</ul>
|
|
|
|
\htmlonly
|
|
Go to the <a href="install.html">next</a> section.
|
|
\endhtmlonly
|
|
|
|
*/
|
|
|