6. Doxygen Documentation

All Fortran, C, and C++ code in UFS_UTILS shall be documented using doxygen.

All files, modules, module variables, and subprograms must have a doxygen documentation block. All function and subroutine parameters must be documented. All files, modules, and subprograms will identify the author(s).

The presence of doxygen documentation is checked in the Continuous Integration runs. Code cannot be merged without doxygen documentation.

Documentation contents are reviewed as part of code review. Documentation will use proper grammar, complete sentences, and proper capitalization and punctuation.

Some specifics when using doxygen:

• Doxygen block for each:
  • file
  • subroutine/function
  • public variable
• File:
  • @file on its own line a top of file
  • @brief with one sentence description of file.
  • @author at file level with full names (if known).
• Subroutine/Function:
  • Brief tag is automatic, so don't use it
  • @param for every argument; in, out, or inout
  • @author
• Function/subroutine names in documentation in lowercase with parens: "fun1()"
• One space before new sentence.

For examples, please see the chgres_cube program source code.

To build the doxygen, add -DENABLE_DOCS=ON to the CMAKE_FLAGS. The html will be located in ./build/docs/html. One way to view the html is by creating an empty gh-pages branch under your fork. Then commit the html and push the branch to github. To view, go to https://USERNAME.github.io/UFS_UTILS/