Improving ADMB Documentation

Identifying documentation priorities

At our inaugural meeting last January, we discussed using Rick Methot's Stock Synthesis program to help identify priorities for improving existing ADMB documentation. Rick sent me the template file for for SS2. I ran tpl2cpp ss2 to generate the corresponding .cpp and .htp files and then ran doxygen to produce a framework for documentation. The resulting document is  here.

Select the Classes, Class Members, Function tabs (or click here) to see a list of functions used by SS2. Most of the functions are specific SS2 functions generated by the ADMB FUNCTION keyword and are therefor members of the class model_parameters, a derived class of model_data (i. e. get_growth2,  get_selectivity,  get_initial_conditions,  get_time_series,  evaluate_the_objective_function,  get_posteriors ,  get_MSY_forecast,  write_summaryoutput,  write_rebuilder_output, write_nudata,  write_nucontrol,  Do_Equil_Calc,  Make_AgeLength_Key,  Make_FishSelex, write_bigoutput).The rest are presumably ADMB functions ether explicitly invoked by SS2 or generated automatically by ADMB.

Based on the SS2 documentation outline, here are some candidate priorities for improving the ADMB documentation:

1. Functions having to do with phases of the estimation. Phased estimation is discussed in several places in the ADModel Builder documentation, but I cannot find a definitive list documenting all of the functions returning phase information.

2. The Variables tab lists all of the varialbes used in the model. Perhaps Rick can help identify the ADMB variables that need more documentaion.

3. The ad_comm class. Use of this class is not revealed by doxygen because fvar.hpp was not included in the documentation request to doxygen. ss2 uses ad_comm::change_datafile_name("..") and  ad_comm::change_pinfile_name("..."). The ADModel Builder documentation discusses ad_comm::change_datafile_name("..") fairly well, but there is no mention of other members of this class. There is useful stuff in this class, and it should be documented. This class is currently declared in fvar.hpp and would thus appear to be part of the autodif library.

 

Comments on doxygen

This is an extremely useful bit of public domain software. It is relatively easy to use and produces a nice document. It has some problems with ADMB template files, though. It does not recognize ADMB keywords (i. e. FUNCTION, PARAMETER_SECTION) and "declaration (i. e.  4darray,  init_bounded_vector). Furthermore, tpl2cpp does not correctly interpret standard C type comments (/* ... */) or pass C++ comments (// ...) through to the C++ file. It might be possible to change tpl2cpp, but it would be more useful to figure out how to hack doxygen to work more easily with ADMB syntax.

 

Documenting the APIs 

The "javadoc" approach to documenting APIs is arguably one of the factors that has enabled java to become so nearly ubiquitous.  If you have never seen javadocs in action, check out the GWT documentation. I have made a couple of starts to documenting the AUTODIF Library API using doxygen to document some of the dvector class. It is very far from complete. The First Attempt puts all of the comments in the header file, fvar.hpp and uses lots of doxygen bells and whistles. The Second Attempt attempts to minimize the extra text in the header file and place detailed documentation in the source code files. The second is also simpler and, to my eyes, nicer. The frame widget on the left is a handy way to get into the code. The Third Attempt applies a different "skin" to the standard doxygen output using a tool called Synsys Dox to produce output that looks very much like a true javadoc. Indeed the Sunsys Dox output uses a lot of Java-derived jargon, but it is a much simpler interface than the default doxygen output.

 

My experience doxygen has been very favorable. Doxygen is not difficult to use, and the defaults are not too bad. It is, however, a rich program, so it takes a bit of fiddling to get it to look like you want. Details of the style are defined  in cascading style sheets, so it would not be difficult for a designer with CSS expertize to customize the look and feel of the documentation to be consistent with the general ADMB Project web presence.