Draft API Documentation

Draft Documentation

This documentation is generated by the Doxygen source code documentation tool. It is presented in two formats, (1) the default Doxygen style and (2) a Javadoc-like style developed by Sunsys.

Default Doxygen Style

• Read on-line
• Download a copy.

Javadoc Style

Sunsys software is an orphan and is not fully compliant with current  Doxygen releases. Consequently, some Doxygen features are not supported by the modification, such as \verbatim and LaTeX formula rendering. Some of the Javadoc-style documentation, therefore, looks a bit odd. Sunsys Dox is an open source project, so if some one wanted to take the trouble, it might be possible to modify it.

• Read on-line
• Download a copy.

Writing Documentation

The main AUTODIF library header file, fvar.hpp, is already very long. We should try to minimize the amount of documentation added to this file. The main reasons to add comments to header files is to document class member variables, in-line functions and macros. Class methods (member functions) can be documented in the C++ source file.

Here is a fragment of the fvar.hpp showing documentation of class dvector member variables:

  class dvector /// Vector of double precision numbers
  {
  protected:
    double * v;    ///< pointer to the data
    int index_min; ///< minimum valid subscript 
    int index_max; ///< maximum valid subscript
    /// pointer to vector housekeeping object
#if defined(THREAD_SAFE)
    ts_vector_shapex * shape;
#else
    vector_shapex * shape;
#endif

The Doxygen construct "///<" is used for comments placed in the code after the end of documented statement.

The Doxygen construct "///" is used for comments placed in the code before the documented statement.

Heres is a fragment of code from dvector.cpp showing documentation of a constructor:

    /**
    \brief Copy constructor.
    This constructor make a "shallow" copy. Values of existing pointers are copied. No memory
    is allocated. If a new object is required the assignment operator should be used.
    Invoked by the compiler when calling a function containing an argument of class %dvector
    passed by value. 
    */
 dvector::dvector(_CONST dvector& t)
 {

Text between "/**" and "*/" is interpreted by Doxygen. The "\brief" tag indicates a  brief comment included in the summary list of member functions. The remainder of the comment is included in the main entry for the function. Brief comments can also be included by using the Javadoc style of comment where text to the first period is considered a brief comment. The rest of the comment is detail.

Getting Started with Doxygen

Head to the Doxygen site, and download and install the current Doxygen version for your OS. Download the ADMB source code and docs directory from the ADMB svn server. Chnge to directory trunk/docs/APIs. Edit the Doxygen configuration file, Doxyfile, to include the source code file you want to work on. It must be listed in the INPUT tag as follows:

INPUT                  = ./dox-share/mainpage.txt \
                         ../../linad99/fvar.hpp \
                         ../../linad99/dvector.cpp \
                         ../../linad99/dvect5.cpp

This listing is dependent on directory structure. If yours is different, you will need to change it accordingly. This method  of specifiying input files will soon get awkward, but it will do for now. There is a Makefile in the APIs directory that works under linux. It makes both the default and tje Javadoc style documentation and displays them both with Firefox.

Doxygen is pretty rich and has many options, so it wouldn't hurt to glance at the documentation before you get too far. You can also see some examples in dvector.cpp

Doxygen works with windows and even comes with a wizard. No attempt has been made to generate the ADMB API documentation on a windows machine.