Introduction

Documenting the code is a fundamental aspect of code development and maintenance. This describes how the LION code documentation is organized, using Doxygen, and how code developers can further add to this documentation.

To actually produece the documentation, go to ~src_f90/ and type "make documentation" or 'make documentation_ITM" or "make documentation_IMAS". This will produce html documentation in the subdirectory ~/DOC/Doxygen/html/. Just open the index.html there with any browser.

Doxygen (http://www.stack.nl/~dimitri/doxygen/) is a standard tool for generating documentation from annotated source code. Primarily geared to C++, it also supports, among others, Fortran - with a few limitations that require some constraints, see section 'Call and caller graphs' below.

Doxygen can be obtained under the general public GNU license. Binary distributions can be found for Linux, Windows and Mac OSX platforms (http://www.stack.nl/~dimitri/doxygen/download.html#srcbin)

Doxygen generates a html document. It can be configured to generate call and caller graphs that clearly expose the code structure, even from un-documented source files - this feature has been implemented here for the LION code.

Documenting the LION code with Doxygen

Doxygen needs a configuration file, by default named 'Doxyfile'. For us, it is located in subdirectory ~/DOC/Doxygen/

It also reads input files, all with extension ~.dox, located in subdirectory ~/DOC/Doxygen/doxy_files/ . In particular, the file 0_hirarchy.dox gives the overall documentation structure and page and subpage organization. Pages can be further subdivided in sections and subsections.

All ~.dox files must start with a line

/*!

and end up with a line

*/

Doxygen will create the documentation of the list of source code files specified by the variable FILE_PATTERNS in the Doxyfile file.

In the source code, Doxygen-recognized comments are introduced in the Fortran source code as

!>

The comments can include some keywords, such as:
'brief' (preceded with the '@'): will make what follows appear in the file summary. (Hint: a line with only !> should follow this statement to separate it from the mode detailed documentation)
Example:

!> @brief Set auxiliary values
!>
!> Get some parameters from CHEASE namelist, check input consistency and define some auxiliary variables

It is good practice to add at least the 'brief' documentation for all subroutines anf functions of the source code, just before each 'subroutine ...' or 'function ...' statement.

Other useful keywords are 'todo', 'deprecated' and 'bug' (preceded with a '@'). Doxygen will highlight these statements and also automatically generate lists of all the 'toto', 'deprecated', respectively 'bug' statements.

Inline LaTeX formulas, e.g. \( dK_n/d\eta \), can be inserted in the documentation, by placing them between a pair of

\f$

commands. See more under https://www.stack.nl/~dimitri/doxygen/manual/formulas.html

Tables can be generated simply with markdown extensions, https://www.stack.nl/~dimitri/doxygen/manual/markdown.html#markdown_extra

Call and caller graphs

Doxygen is configured to automatically generate call and caller graphs of all subroutines and functions that are present in the FILE_PATTERNS specified in the Doxyfile file. These graphs can be found in the html produced by Doxygen under Files > File List > src_f90.

The call/caller graphs have hyperlinks in every box, which greatly facilitates the navigation through the code structure.

With Fortran source, however, there appears to be some bugs in doxygen:

subroutine names containing uppercase characters will not appear in the call/caller graphs
a subroutine named 'data' will also not appear in the call/caller graphs (and there might well be other reserved identifiers)

That is why we recommend, as a 'good practice', to write the names of the subroutines and functions only with lowercase characters.

Todo:: Rewrite all subroutine and function names using lowercase characters only (underscore is OK)