All classes in SimFQT 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 SimFQT 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 ¶m3); 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 };
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. * * ------------------------------------------------------------------------- * * SimFQT - C++ Standard Airline IT Object Library * * Copyright (C) 2009-2010 (\see authors file for a list of contributors) * * \see copyright file for license information * * ------------------------------------------------------------------------- */
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 ¶m2);