Doxygen Style

Introduction

In order to conform with both the Doxygen style and the current C++ style, all lines in the docstring comment blocks should always start with

//! Docstrings to be appeared in the doxygen generated documents

For example, main.c in Athena4.2 utilizing the old/C-style commenting block with /* ... */ will be correctly rendered by Doxygen.

/*! \file main.c
 *  \brief Athena main program file.
 *
 * //////////////////////////// ATHENA Main Program \\\\\\\\\\\\\\\\\\\\\\\\\\\
 *
 *  Athena - C version developed by JM Stone, TA Gardiner, & PJ Teuben.
 *
 *  Significant additional contributions from X. Bai, K. Beckwith, N. Lemaster,
 *  I. Parrish, & A. Skinner.  See also the F90 version developed by JF Hawley
 *  & JB Simon.
 *
 *  History:
 * - v1.0 [Feb 2003] - 1D adiabatic and isothermal MHD
 * - v1.1 [Sep 2003] - bug fixes in eigensystems
 * - v2.0 [Dec 2004] - 2D adiabatic and isothermal MHD
 * - v3.0 [Feb 2007] - 3D adiabatic and isothermal MHD with MPI
 * - v3.1 [Jan 2008] - multiple species, self-gravity
 * - v3.2 [Sep 2009] - viscosity, resistivity, conduction, particles, special
 *                     relativity, cylindrical coordinates
 * - v4.0 [Jul 2010] - static mesh refinement with MPI
 *
 * See the GNU General Public License for usage restrictions. 
 *                                          
 * PRIVATE FUNCTION PROTOTYPES:
 * - change_rundir() - creates and outputs data to new directory
 * - usage()         - outputs help message and terminates execution          */

However, main.cpp in Athena++ utilizing the new/C++-style commenting block with // will not be rendered by Doxygen correctly. Doxygen recoginzes only the first line with //!.

/////////////////////////////////// Athena++ Main Program ////////////////////////////////
//! \file main.cpp
//  \brief Athena++ main program
//
// Based on the Athena MHD code (Cambridge version), originally written in 2002-2005 by
// Jim Stone, Tom Gardiner, and Peter Teuben, with many important contributions by many
// other developers after that, i.e. 2005-2014.
//
// Athena++ was started in Jan 2014.  The core design was finished during 4-7/2014 at the
// KITP by Jim Stone.  GR was implemented by Chris White and AMR by Kengo Tomida during
// 2014-2016.  Contributions from many others have continued to the present.
//========================================================================================

For the correct rendering, the commenting block should look like (see main.cpp in the doc branch)

//! \file main.cpp
//! \brief Athena++ main program
//!
//! Based on the Athena MHD code (Cambridge version), originally written in 2002-2005 by
//! Jim Stone, Tom Gardiner, and Peter Teuben, with many important contributions by many
//! other developers after that, i.e. 2005-2014.
//!
//! Athena++ was started in Jan 2014.  The core design was finished during 4-7/2014 at the
//! KITP by Jim Stone.  GR was implemented by Chris White and AMR by Kengo Tomida during
//! 2014-2016.  Contributions from many others have continued to the present.

Note that the blank line starting with \\! after \brief is necessary to separate the brief and detailed decription. Additional blank line separates paragraphs.

Recommended Commenting Style

After reviewing the Doxygen manual (https://www.doxygen.nl/manual/index.html), we have a few recommendation to documenting the code.

• Use //! for the comments to be recognized by Doxygen. See Special Comment Blocks.

• Document all functions at least using //! \fn and //! \brief. Without such structural commands, doxygen special comment blocks will find function, class, struct, enum, etc right next to the comment and attach the comment to it.

• Here's an important remark from the doxygen manual. Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

  //! \file
  

• Variables can also be docummented. Two example styles are possible

  //! description of variable
  int var;
  

  or

  int var; //!> short description of variable
  

• To make the same comment applied to many variables, use grouping //!@{ ... //!@}

  //!@{
  //! common description of variables
  int var1, var2, var3;
  //!@}
  

• Doxygen supports Markdown. A usage example may be found at src/parameter_input.cpp

• Conider to use additional commands like //! \todo, //! \deprecated, //! \warning, and //! \note that Doxygen renders nicely. Some examples can be found in src/bvals/bvals.cpp

• Equations can be added with \f$ ... \f$ for inline equations and \f[ ... \f] for displayed equations. See src/task_list/time_integrator.cpp for an example.

Generate Doxygen Pages

Currently, in the doc branch, we place a configure file doc/Doxyfile.in. After installing doxygen (note that there are binary builds available for MacOS via homebrew or linux via apt-get, you can run

cd doc/
doxygen Doxyfile.in 1> doxy.log 2> doxy.err

to create the doxyhtml/ folder and open

doxyhtml/index.html

file to browse the document page!

The doc branch is still under development.