diff -r 000000000000 -r 42188c7ea2d9 Orb/Doxygen/doc/index.doc --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Orb/Doxygen/doc/index.doc Thu Jan 21 17:29:01 2010 +0000 @@ -0,0 +1,213 @@ +/****************************************************************************** + * + * + * + * Copyright (C) 1997-2008 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 index +\if logo_on + +\htmlonly + doxygen

+Version: $(VERSION) +\endhtmlonly + +\endif + +

Introduction

+Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL +(Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D. + +It can help you in three ways: +

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), + 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. +
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. + You 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. +
You can even `abuse' doxygen for creating normal documentation (as I did + for this manual). +

+ +Doxygen is developed under Linux +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. + +\n This manual is divided into three parts, each of which is divided into several +sections. + +The first part forms a user manual: +

Section \ref install discusses how to + download, compile and install + doxygen for your platform. +
Section \ref starting tells you how to generate your first piece of + documentation quickly. +
Section \ref docblocks demonstrates the various ways that code can + be documented. +
Section \ref lists show various ways to create lists. +
Section \ref grouping shows how to group things together. +
Section \ref formulas shows how to insert formulas in the documentation. +
Section \ref diagrams describes the diagrams and graphs that doxygen can generate. +
Section \ref preprocessing explains how doxygen deals with macro definitions. +
Section \ref autolink shows how to put links to files, classes, + and members in the documentation. +
Section \ref output shows how to generate the various output formats + supported by doxygen. +
Section \ref searching shows various ways to search in the HTML documentation. +
Section \ref customize explains how you can customize the output generated + by doxygen. +
Section \ref custcmd show how to define and use custom commands in your comments. +
Section \ref external explains how to let doxygen create links to externally generated documentation. +
Section \ref faq gives answers to frequently asked questions. +
Section \ref trouble tells you what to do when you have problems. +

+ +The second part forms a reference manual: + +

Section \ref features presents an overview of what doxygen can do. +
Section \ref history shows what has changed during the development + of doxygen and what still has to be done. +
Section \ref doxygen_usage shows how to use the \c doxygen program. +
Section \ref doxytag_usage shows how to use the \c doxytag program. +
Section \ref doxywizard_usage shows how to use the \c doxywizard program. +
Section \ref installdox_usage shows how to use the \c installdox + script that is generated by doxygen if you use tag files. +
Section \ref config shows how to fine-tune doxygen, so it + generates the documentation you want. +
Section \ref commands shows an overview of the special commands that can be + used within the documentation. +
Section \ref htmlcmds shows an overview of the HTML commands that + can be used within the documentation. +
Section \ref xmlcmds shows an overview of the C# style XML commands that + can be used within the documentation. +

+ +The third part provides information for developers: + +

Section \ref arch gives a global overview of how doxygen is internally + structured. +
Section \ref perlmod shows how to use the PerlMod output. +
Section \ref langhowto explains how to add support for new + output languages. +

+ +\n

Doxygen license

+ +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. + +

User examples

+ +Doxygen supports a number of \ref output "output formats" where HTML is the +most popular one. I've gathered +\htmlonly +some nice examples +\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 +\htmlonly +list of projects +that use doxygen. +\endhtmlonly +\latexonly +list of projects that use doxygen (see {\tt http://www.doxygen.org/projects.html}). +\endlatexonly +If you know other projects, let me +know and I'll add them. + +

Commercial Support

+ +I'm currently investigating the possibilities of providing +commercial support for doxygen. The forms of support I'm thinking of +are: +

implementing features, +
fixing bugs, +
providing priority help in answering questions. +

+To get a better understanding of the feasibility, +please let me know if you +have a need for this type (or another type) +of doxygen related commercial support. + +

Future work

+Although doxygen is successfully used by large number of companies and +open source projects already, there is always room for improvement. +

+You can submit enhancement requests in +the bug tracker. +Make sure the severity of the bug report is set to "enhancement". + +

Acknowledgements

+\addindex acknowledgements +Thanks go to: +

\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. +
All people at Qt Software, for creating a beautiful GUI Toolkit + (which is very useful as a Windows/Unix platform abstraction layer :-) +
My brother Frank + for rendering the logos. +
Harm van der Heijden for adding HTML help support. +
Wouter Slegers of + Your Creative Solutions + for registering the www.doxygen.org domain. +
Parker Waechter for adding the RTF output generator. +
Joerg Baumann, for adding conditional documentation blocks, + PDF links, and the configuration generator. +
Tim Mensch for adding the todo command. +
Christian Hammond for redesigning the web-site. +
Ken Wong for providing the HTML tree view code. +
Talin for adding support for C# style comments with XML markup. +
Petr Prikryl for coordinating the internationalisation support. + All language maintainers for providing translations into many languages. +
The band Porcupine Tree for + providing hours of great music to listen to while coding. +
many, many others for suggestions, patches and bug reports. +

+*/ +