Documentation Rules

General Rules

All classes in SimCRS should be properly documented with Doxygen comments in include (.hpp) files. Source (.cpp) files should be documented according to a normal standard for well documented C++ code.

An example of how the interface of a class shall be documented in SimCRS is shown here:

/*!
 * \brief Brief description of MyClass here
 *
 * Detailed description of MyClass here. With example code if needed.
 */
class MyClass {
public:
  //! Default constructor
  MyClass(void) { setup_done = false; }

  /*!
   * \brief Constructor that initializes the class with parameters
   *
   * Detailed description of the constructor here if needed
   *
   * \param[in] param1 Description of \a param1 here
   * \param[in] param2 Description of \a param2 here
   */
  MyClass(TYPE1 param1, TYPE2 param2) { setup(param1, param2); }

  /*!
   * \brief Setup function for MyClass
   *
   * Detailed description of the setup function here if needed
   *
   * \param[in] param1 Description of \a param1 here
   * \param[in] param2 Description of \a param2 here
   */
  void setup(TYPE1 param1, TYPE2 param2);

  /*!
   * \brief Brief description of memberFunction1
   *
   * Detailed description of memberFunction1 here if needed
   *
   * \param[in]     param1 Description of \a param1 here
   * \param[in]     param2 Description of \a param2 here
   * \param[in,out] param3 Description of \a param3 here
   * \return Description of the return value here
   */
  TYPE4 memberFunction1(TYPE1 param1, TYPE2 param2, TYPE3 &param3);

private:

  bool _setupDone;         /*!< Variable that checks if the class is properly 
                                initialized with parameters */
  TYPE1 _privateVariable1; //!< Short description of _privateVariable1 here
  TYPE2 _privateVariable2; //!< Short description of _privateVariable2 here
};

File Header

All files should start with the following header, which include Doxygen's \file, \brief and \author tags, $Date$ and $Revisions$ CVS tags, and a common copyright note:

/*! 
 * \file 
 * \brief Brief description of the file here
 * \author Names of the authors who contributed to this code
 * \date Date
 * 
 * Detailed description of the file here if needed.
 *
 * -------------------------------------------------------------------------
 *
 * SimCRS - C++ Simulated Travel Distribution System Library
 *
 * Copyright (C) 2009-2011  (\see authors file for a list of contributors)
 *
 * \see copyright file for license information
 *
 * -------------------------------------------------------------------------
 */

Grouping Various Parts

All functions must be added to a Doxygen group in order to appear in the documentation. The following code example defines the group `my_group':

/*! 
 * \defgroup my_group Brief description of the group here
 * 
 * Detailed description of the group here 
*/

The following example shows how to document the function myFunction and how to add it to the group my_group:

/*!
 * \brief Brief description of myFunction here
 * \ingroup my_group
 *
 * Detailed description of myFunction here
 *
 * \param[in] param1 Description of \a param1 here
 * \param[in] param2 Description of \a param2 here
 * \return Description of the return value here
 */
TYPE3 myFunction(TYPE1 param1, TYPE2 &param2);