Rosetta++ Commenting Guidelines          Last Updated:June 8, 2005

Introduction

The comment blocks at the beginning of Rosetta functions have been formatted to be compatible with the Doxygen auto-documentation program.

• Comment Format

• General Notes

• Commands

• Doxygen Notes

• Template Header

Comment Format

Here is an sample comment block. Example comments are italicized.

//////////////////////////////////////////////////////////////////////
/// @begin fold_every_protein
///
/// @brief
/// finds the correct fold for every protein sequence
///
/// @detailed
/// This is an implementation of an algorithm I found in an
/// old cook book. It always works
/// (i. e. this put CASP out of business)
///
/// @param[in] sequence - aa sequence
/// @param[out] xyz - coordinates
/// @param[in,out] bk_soda - amount of baking soda left
///
/// @return
/// 1 if fold is right and you have enough baking soda,
/// 0 if fold is right and you DON'T have enough baking soda
///
/// @global_read
/// ingredients in baking.h the_real_energy_function in universe.h
///
/// @global_write
/// ingredients
///
/// @remarks
/// Also makes a really tasty raisin-nut bread
///
/// @references
/// Smith, T., H., R., W. (1962) "Good Healthy
/// Old World Meals in 5 Steps and Analytic Solutions
/// to All N-Body Calculations in 4 Steps" 123-34.
/// (after the pot pie recipe)
///
/// @authors Glenn Butterfoss
///
/// @last_modified June 33, 2004
/////////////////////////////////////////////////////////////////////////


This gets marked-up to look like:

---

Function Documentation

finds the correct fold for every protein sequence

fold_every_protein

Detailed:

This is an implementation of an algorithm I found in an old cook book. It always works (i. e. this put CASP out of business)

Parameters:

Returns:

1 if fold is right and you have enough baking soda, 0 if fold is right and you DON'T have enough baking soda

Global Read:

ingredients in baking.h the_real_energy_function in universe.h

Global Write:

ingredients

Remarks:

Also makes a really tasty raisin-nut bread

References:

Smith, T., H., R., W. (1962) "Good Healthy Old World Meals in 5 Steps and Analytic Solutions to All N-Body Calculations in 4 Steps" 123-34. (after the pot pie recipe)

Authors:

Glenn Butterfoss

Last Modified:

June 33, 2004

Definition at line 43 of file mm.cc.

General Notes

• Doxygen reads in "///" comments. Currently, it is set up to ignore comments within the function bodies (regardless of how many slashes they begin with). Additionally, the entire comment block must have at least 3 slashes, otherwise doxygen may skip part of the block.

• The doxygen commands begin with "@". It is important to leave a space between the command and the slashes (use "/// @begin" not "///@begin" ... I have noticed that the program may become confused with this.

• Doxygen does not use the newlines from the source file. You need to add an explicit "\n" to get a carriage return in the html.

  Commands

• @brief Follow this with a short line or two about the function. Note: Only things up until the first empty "///" line or next "@" command will be placed after the function name at the top of the html page.

• @param The function parameters can be specified as: @param, @param[in], @param[out], or @param[in,out]. Follow with the parameter name and a short description. Do not put a dash before the parameter name (it does not look as good).

• @return (if needed)

• @global_read and @global_write Where you are getting and placing information (namespaces, *.h files) ... be aware that many global reads and writes are yet undocumented.

• @remarks Put more information here that does not seem to belong in the detailed section. Exactly what differentiates such things is left to the aesthetic tastes of the programmer.

  Doxygen Notes

• Doxygen reads in configuration parameters from a "Doxyfile". (Called Doxyfile in the Rosetta++ CVS).

• The index.html page is generated from comments in doxygen.h

• Graphs are generated with the dot program from the graphiz package. (The path of which is specified in the Doxyfile.) The line and box colors are described here.

  Template Header