Doxygen

Introduction

Doxygen is the code documentation tool used by this project. It can do amazing things that we are not yet taking advantage of, and in particular can generate very nice manuals. It is not that hard, but of course there is

• a little learning barrier, and
• the need for a few style conventions.

Details

The files `src/example_doc.h` and `src/example_doc.cc` illustrate how to use Doxygen to document your code. You can see here how "Example documentation" was introduced as a module due to the group definition - look in the module to see how things appear.

Of particular note

• \file is required (best put near the top of your file) otherwise doxygen will not look at it. Immediately below the '\file` you can put brief and full/detailed documentation on the file or module contents.
• \defgroup and ingroup can be used to create modules and link text into modules.
• Parameters and return values can and should be consistently documented.
• Links to classes, functions, and files are automatically generated.

Doxygen has section and subsection commands that introduce additional structure on the main page. We will defer using those until we have both cleaned up the documentation we have and understood how we want to organize things.

For now, we have introduced (in doc/mainpage.h) high level doxygen groups that roughly follow the directory structure (since we do seem to have thought about that).

• configuration - anything to do with installation, building, etc.
• libraries
  • parallel_runtime - to hold everything in src/world
  • mra - everything in lib/mra
  • tensor -
  • linalg -
  • solvers -
  • misc -
• applications
  • examples
  • moldft
  • tdse

To get the right structure, this means an example program should be documented with something like

  /*!
    \file examples/cool.cc
    \brief You won't believe your eyes
    \defgroup cool_example Example of total coolness
    \ingroup examples
  
    It is not possible to overstate how cool this example is.
    Compared to this example, James Dean was ...

   @{
  */

    ...

  /* @} */ 

I've had mixed experience with the @{...@} method of including things in a group. More reliable results are obtained from annotating each class and top-level function with \ingroup xxxx.