Xmipp

This is a brief outline of Doxygen rules. A complete reference is available at the Doxygen manual

For generating the whole documentation, go to the main Xmipp directory and type

$ ./createDocumentation.sh

1. For a brief comment use ///

/// This method does something
void doSomething();

2. For a detailed comment use /** ... */

/** This method requires a much longer
  * comment because it's complicated.
  * Extra * at the beginning of each line
  * must be used if @code tags are present.
  */
void doComplicated();

3. For a brief comment AFTER a declaration use ///<

void doStrangeThings(); ///< Indeed, strange things...

4. For a detailed comment AFTER a declaration use /**< ... */

void doNothing(); /**< Yep. Nothing. It may seem a bit strange
                       to have a method without any purpose, but
                       we are so cool we decided to have one. */

5. To make logical groups:

  • Start with a @defgroup clause
       /// @defgroup MyGroup My group description
       

  • Assign members to the group by using the @ingroup clause
       /// @ingroup MyGroup
       

  • Create subgroups with @ingroup too
       /// @defgroup MySubgroup My subgroup description
       /// @ingroup MyGroup
       
6. For code examples use @code and @endcode tags
/** @code
  * for (int i=0; i<100; i++)
  *     doSomething(i);
  * @endcode
  */

7. For documenting a class:

/** A class.
  * Details
*/
class Test
{
  public:
    //@{
    /** Same documentation for both members. Details */
    void func1InGroup1();
    void func2InGroup1();
    //@}

    /** Function without group. Details. */
    void ungroupedFunction();
    void func1InGroup2();
  protected:
    void func2InGroup2();
};

8. For documenting a group with several functions use:

/** @name Group2
 *  Description of group 2. 
 */
//@{
/** Function 2 in group 2. Details. */
void Test::func2InGroup2() {}
/** Function 1 in group 2. Details. */
void Test::func1InGroup2() {}
//@}

-- AlfredoSolano - 15 Jan 2007