README.doxygen

Using Doxygen for UltraScan code documentation

This summary is taken from the Doxygen manualfound at
http://www.stack.nl/~dimitri/doxygen/manual.html

Note: TOP below refers the the UltraScan III top level source
files extracted from subversion.

1. Overview

There are three steps needed to get Doxygen generated documentation.

  a.  Document the source code with special Doxygen tags
  b.  Create a Doxyfile configuration file
  c.  Create a DoxygenLayout.xml configuration file
  d.  Run 'doxygen' from TOP

The configuration files are located in TOP.  A Doxyfile.warn file
is produced, but will be empty if no warnings are issued.

They are set to only create html documentation.  These are
created in TOP/doc/doxygen/html/.  There are additional options
in the Doxyfile configuration file that may be useful in the 
future.

2. Customization of Doxygen html files.

There is some minor customimization of the html files as the 
UltraScan3 logo is placed at the top of each generated page.
This is down with adding ultrascan3.png and header.html to
TOP/doc/doxygen/ and specifying the location of the custom
header file in the Doxyfile configuration file.


3. Documenting source code.

Generally, most of the Doygen markup is located in the header files,
but .cpp files can have Doygen markup also.

The markup consists of special C or C++ comment blocks like:

//!  Some markup

/*!
     Some markup
*/

/**
     Some markup
*/

If you forget the !, then the markup is not recognized.

Usually, the markup goes immediately before the code being described, but it
can go after by adding a < to the comment marker:

struct
{
  int    a;  //!< Document a
  double b;  //!< Document b
}

There are many special commands that start with a backslash.  Thes are
documented at http://www.stack.nl/~dimitri/doxygen/commands.html.
The ones most useful are:

  \file  
  \brief
  \note
  \param
  \retval
  \class
  \enum
  \ref
  \anchor

4. The main page is documented in TOP/mainpage.dox. 

By putting a number of column-aligned minus signs at the start of a line, a
bullet list will automatically be generated. Numbered lists can also be
generated by using a minus followed by a hash. Nesting of lists is allowed and
is based on indentation of the items.