Doxygen

Using Doxygen

This page outlines the use of doxygen in MOM6. See generating HTML with doxygen at the bottom of this page to locally generate the HTML documentation while you are developing. Instructions for uploading the HTML to the MOM6 API documentation site are outlined in the README.md of the gh-pages branch.

---

Doxygen style guide

Doxygen comments begin with !> or !<, the bracket-direction indicating the Fortran line with which the comment is associated. Multi-line comments are indicated using !! with no blank lines within the multi-line comment.

The documentation for doxygen itself is quite comprehensive.

Module documentation

Header

We like to keep the header concise to facilitate navigating the module. A brief description of the module and a reference to the license is all that is needed:

!> Implements the Mesoscale Eddy Kinetic Energy framework
module MOM_MEKE

! This file is part of MOM6. See LICENSE.md for the license.

Module description

The high-level or verbose module description should be place at the end of the module, immediately above the end module statement. Also note that the module name provided to the doxygen command \namespace should be in all lowercase (because doxygen adheres to the case insensitive Fortran convention):

!> \namespace mom_meke
!!
!! \section section_MEKE The Mesoscale Eddy Kinetic Energy (MEKE) framework
!!
!! The MEKE framework accounts for the mean potential energy removed by
!! ...

end module MOM_MEKE

Module data types

Many MOM6 modules have their own "control structures" and defined types:

!> Control structure that contains MEKE parameters and diagnostics handles
type, public :: MEKE_CS ; private
  real :: MEKE_FrCoeff  !< Efficiency of conversion of ME into MEKE (non-dim)
  real :: MEKE_GMcoeff  !< Efficiency of conversion of PE into MEKE (non-dim)
  real :: MEKE_damping  !< Local depth-independent MEKE dissipation rate in s-1.
  real :: MEKE_Cd_scale !< The ratio of the bottom eddy velocity to the column mean
                        !! eddy velocity, i.e. sqrt(2*MEKE). This should be less than 1
                        !! to account for the surface intensification of MEKE.

Grouped variables

Most variables and objects should be individually documented but some select kinds can be grouped, particularly the handles for diagnostics and clocks. e.g.

!>@{
!! Diagnostic identifier
integer :: id_u = -1, id_v = -1, id_h = -1
!>@}

will document each "id" with the same label "Diagnostic identifier".

Equations

Equations are facilitated using LaTeX markup between \f$ ... \f$ or \f[ ... \f] delineations. The delineations themselves make comments less readable so we prefer to use equations only in the module description at the bottom of the module. This is not a hard rule, just a preference.

!! \subsection section_KPP_nutshell KPP in a nutshell
!!
!! Large et al., 1994, decompose the parameterized boundary layer turbulent flux of a scalar, \f$ s \f$, as
!! \f[ \overline{w^\prime s^\prime} = -K \partial_z s + K \gamma_s(\sigma), \f]
!! where \f$ \sigma = -z/h \f$ is a non-dimensional coordinate within the boundary layer of depth \f$ h \f$.
!! \f$ K \f$ is the eddy diffusivity and is a function of position within the boundary layer as well as a
!! function of the surface forcing:
!! \f[ K = h w_s(\sigma) G(\sigma) . \f]

Subroutines and functions

Subroutine descriptions should be easily readable in the code. They do not necessarily have to be short but human readable. If equations are needed we prefer to put them in a section of the module description which will appear at the bottom of the file:

!> Integrates forward-in-time the MEKE eddy energy equation.
!! See \ref section_MEKE_equations
subroutine step_forward_MEKE(MEKE, h, visc, dt, G, CS)

Arguments documentation should be on the same line, if possible, using !<. If not the a comment above the argument declaration uses !>, and after uses, !<. All raw data-type arguments need units.

  type(MEKE_type),                       pointer       :: MEKE !< MEKE data
  real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in)    :: h    !< Layer thickness (m or kg m-2)
  type(vertvisc_type),                   intent(in)    :: visc !< The vertical viscosity type
  real,                                  intent(in)    :: dt   !< Model(baroclinic) time-step (s)
  type(ocean_grid_type),                 intent(inout) :: G    !< Ocean grid
  type(MEKE_CS),                         pointer       :: CS   !< MEKE control structure
  ! Local variables
  integer :: i, j, k

Doxygen does not document variables local to a subroutine or function. There is no harm in using the !< notation to associate comments with variables and it does make the meaning clearer.

---

Generating HTML with doxygen

doxygen requires cmake, flex and bison to be available on your platform. The MOM6 documentation also requries graphviz/dot.

Place the latest version of doxygen within the MOM6/ directory and build doxygen:

cd MOM6-examples/src/MOM6/docs/
git clone https://github.com/doxygen/doxygen
(cd doxygen; cmake -G "Unix Makefiles" .)
(cd doxygen; make)

To generate HTML do the following:

./doxygen/bin/doxygen Doxyfile_nortd

and the generated HTML will appear in a new directory APIs/. The front-page is called APIs/index.html. This will create HTML files in the directory html/. Point your browser to html/index.html to look at the generated documentation.

Updating the gh-pages branch

WARNING: We re-write history on the gh-pages branch.

The volume of the generated content is so huge that if we kept every version of it on the gh-pages branch the repository would grow uncontrollably. To avoid this, we keep place changes to style-sheet, front-pages, etc., on branch gh-pages-static and then "reset" branch gh-pages to the HEAD of branch gh-pages-static.

The procedure for updating the published doxygen-generated content is given in README.md on the gh-pages-static branch.