MADNESS coding style

Collaboration diagram for MADNESS coding style:

MADNESS code should be documented using doxygen-style comment blocks. More information on doxygen can be found at the doxygen website. This module illustrates how to document your files with doxygen.

General guidelines for doxygen

Every file needs \file and \brief near the top, and usually \addtogroup or . then the file-level documentation acts as documentation for that module or group, otherwise it acts as documentation for the file. Note that doxygen is really picky about placement and association of comments so you always have to check what was generated.

Links to known classes (such as madness::World), functions (such as madness::error()), and files (such as madness.h) are made automatically.

Subsection title

Use the \par directive to make subsections with an optional heading. Doxygen's section and subsection directives should not be used for now.

Example files

Here is an example header file that appropriately uses doxygen comment blocks.

/// \file example_doc.h
/// \brief Brief description of this file's contents.
/// \ingroup example_group
 
// Add your code to a group, if desired, using the \addtogroup command. See doc/mainpage.h for available groups.
// The @{ and @} commands allow blocks of code to be added to the group.
/// \addtogroup possibly_different_example_group
/// @{
 
/// Every class should be documented (this is the brief line).
 
/// This is the full text ... no need to be verbose, but without
/// documentation your class is nearly useless.
class ExampleClass1 {
public:
    int datum; ///< Each member datum needs at least a brief raison d'etre.
 
    /// Each member function should be documented (this is the brief line).
 
    /// Full documentation of the member function.
    ///
    /// You should document all arguments and return values.
    /// @param[in] hope Optimism level.
    /// @param[in] despair Pessimism level.
    /// @return Cynicism level.
    int reality(int hope, int despair) const;
};
 
/// Brief documentation of a second example class in the group.
  
/// Full documentation of the second example class.
class ExampleClass2 {
public:
    /// Brief documentation of a member function.
 
    /// Full documentation of the member function, including parameters
    /// and return value.
    /// @param[in] fud The current level of fear, uncertainty, and doubt.
    /// @param[in,out] bs The current level of ...
    /// @return Your state of mind.
    int morose(int fud, int& bs) {};
 
    void fred(double mary);    // Fred is documented in example_doc.cc
    // We recommend, however, placing documentation in header files when possible.
};
 
int stuff; ///< Global variable in the example group.
 
/// Global function in the example group.
 
/// @param[in] a An input argument.
/// @return The return value.
int example_func(int a);
 
// Closing group membership.
/// @}

And here's the corresponding implementation file.

/// \file example_doc.cc
/// \brief Illustrates how to split documentation between files.
/// \ingroup example_group
 
#include "example_doc.h"
 
/// Brief documentation of a class member declared in the header file.
 
/// Full documentation of the class member.
/// @param[in] mary Mary's current bank balance.
void ExampleClass2::fred(double mary) {
    return;
}