doxygen guidelines

doxygen is a tool that can be used to generate documentation from comments found in source code provided that they are suitably formatted. doxygen can generate documentation in a variety of formats including HTML and PDF. to help you using doxygen a configuration file (Doxyfile) that reflects our preferences is located in the rapple cvs module tree.

the following guidelines apply to code documentation using doxygen within rapple development:

• implementation not interface the bulk of the code documentation is to be made in the implementation file (*.c) rather than the interface (*.h) since when changes are made to code it is more likely the documentation will get updated.
• module level commentary every module should contain sufficiently detailed comments describing its function and purpose. in addition each module should contain a one line brief comment summarising its function. it should be discernable from these comments why the module exists (even long after it was created ;)
• type commentary all types (structures, enums, typedefs, global variables and non-static functions) should have appropriate but preferably brief comments. static (non-global) types and automatic variables may of course be documented but need not necessarily be included in generated documentation.
• function commentary non-static function types such be preceded with the /** identifier and should contain doxygen commands for parameters (@param) and return values (@return) as the following example:
  /**
  This is a sample function. It demonstrates how you should comment your functions.
  @param x, an input parameter
  @return a return code for the caller
  */
  
  typically comments should alert the user to any requirements on parameters, explanation of return values and perhaps warnings about constraints or common errors. usually a few lines is more than sufficient.
• the @ symbol doxygen commands may be preceded with wither \ or @. the tendency has been to perfer the latter so for consistency we encourage its use rather than a backslash ;)