Documenting Code

We use Doxygen for our code documentation. You may generate HTML file with our make targets like this:

make doc

Our Doxygen configuration will generate call/caller graphs, collaboration graphs and inheritance graphs with the GraphViz package.

There are two kinds of documentation. Documentation describing classes, functions, members, name spaces etc. and documentation directly regard implementation. For the first, Doxygen comments in JavaDoc-style must be used, like this:

/**
 * Scale a given vector. Using this function it is ensured that ...
 *
 * \param s the scaling factor
 * \param v the vector to scale
 *
 * \return a copy of v, scaled by d
 *
 * \see otherFunc
 *
 * \note the returned vector is a copy of v
 * \problem consider numerical issues
 *
 * \reminder something to remember
 *
 * \todo{ebaum} make it better
 * \todo make it bad code to ensure ebaum has a lot of work to do
 */
std::vector< double > func( double s, std::vector< double > v ) { ... }

but for the latter (implementation documentation) just two slashes should be used:

if( ( distance( gl_TexCoord[0].xyz, focalPoint2 ) < 0.01 ) )
{
    gl_FragColor = vec4( 0.0, 0.0, 1.0, 1.0 ); // blue
}

Also regard those issues:

• do not add dummy doxygen comments!( They are not useful)

• document where you declare

• use meaningful names for identifiers

• also you may directly document code, be short precise

• document inside the (member-)functions. Ten nested for-loops are not very interpretable if not documented.

• never check in with doxygen warnings

• be short and precise and do not use introductory phrases like This method creates... but instead just start with: Creates...

• whenever using // NOLINT comments to prevent that line from lint checker, think twice if its really needed, and if so write also the reason why behind the comment like this:

  boost::function< void ( boost::shared_ptr< WPropertyBase > ) > callBack = boost::bind( &rerunBuilder, this, _1 ); // NOLINT extra space before (, which is not a function call

• always document the return code

• try to document more the WHY not the WHAT, since for the WHAT you can read the implementation.

But most of all: If you find documents not following this rule, do not leave them broken - fix them if you can or contact the author which you might get with

git annotate Openwalnut.cpp

Of there are many doxygen commands you may use, see Doxygen for more details.