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

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:

!> \class 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 there 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.

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 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 next within the MOM6/ directory:

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

To use doxygen to generate HTML do the following:

./doxygen/bin/doxygen .doxygen

This will create HTML files in the directory html/. Point your browser to html/index.html to look at the generated documentation.