Doxygen is a documentation system for C++, Java, IDL (Corba, Microsoft and KDE-DCOP flavors) and C.

It can help you in three ways:

1. 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.
2. Doxygen can be configured to extract the code structure from undocumented source files. This can be very useful to quickly find your way in large source distributions. The relations between the various elements are be visualized by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.
3. You can even `abuse' doxygen for creating normal documentation.

The Doxyfile in the base distribution is configured to take input from two sources: any code file under src/ and docs/Mainpage.dox. Most documentation for classes and other code constructs should be in the code files, Mainpage.dox should contain the project overview and other high-level documentation related to the project.

Each documented construct in your project should have at least one and possibly two comment blocks immediately preceding the construct. The first and required block is the short description of the construct which MUST start with //!. The second optional block is a long description with parameter and return type specifications which begins with /** and ends with */

Here is an example of a fully documented class. Each element of the class has a short description and some members have a long description. Parameters are identified with @param and return values are identified with @return. Note that in addition to documenting each class member, I have documented the class as well.

  //! Class representing a basic numeric statistic about the machine
  /** 
   * This class contains a status flag and three variables for the 
   * statistic: the current value, the previous value and the rate.
   */
  class Statistic{
  public:
    //! Default constructor - sets all values to 0 or false 
    Statistic();

    //! Get the rate of the statistic
    /** @return the rate of the statistic (usually x per sec or x percent)
     */
    double getValue();

    //! Set the value of the statistic based on text input
    /** @param t The text to parse
     * @return true if the parse worked
     */
    virtual bool parseText(char *t);

    //! Set the value of the statistic directly
    /** @param v The new value
     */
    virtual void setValue(double v);

  protected:
    //! The current value of the stat
    double value;
  };

The contents of the main page of a project are controlled through the file docs/Mainpage.dox. The file starts with a doxygen comment identifier /** and ends with a closing comment identifier */ so that doxygen will know to process the file contents.

The location of items is controlled by doxygen codes - the ones you will probably use are:
\mainpage to start text which will appear on the index page,
\page id Title to put documentation on a separate HTML page and
\section id Title to insert a section into a page.

More information
The main Doxygen site is http://www.doxygen.org.

On RedHat 7.2, you can find the html manual on your system in /usr/share/doc/doxygen-1.2.8.1/html/index.html. Other distributions may have a different doxygen doc directory, named /usr/share/doc/doxygen-xxxx where XXXX is the version installed on your system.

There is a version of the manual available for download as a .tar.gz file doxygen-1.2.8.1.tar.gz. The manual is also available for on-line browsing from this server.