[ag-automation] Questions/Annotations about implementation of fddi

[Thomas Rothfuss]

Robert Schwebel wrote:

 > On Fri, Sep 28, 2007 at 11:18:33AM +0200, Thomas Rothfuss wrote:
 >
 >>> Yes, we'll use doxygen for API documentation. But I think at this stage
 >>> it doesn't make any sense to start writing documentation, because the
 >>> whole APIs are under heavy progress. Once they have stabilized, you're
 >>> welcome to help in this area.
 >>
 >>
 >> Fine (since I know doxygen ;-)).
 >
 >
 >
 > Can you provide a template which shows how to correctly annotate C style
 > classes with doxygen markers? I couldn't find a good way which produces
 > nice class descriptions out of plain C code (but I didn't try very hard).
 >
 > Robert



Well I used it with C++. But for C it is similar. There has to be a
file named doxyfile (default name). In this file there are the
settings and pathnames of the files to documentate.

In the doxygen documentation there is a section named
"Special Commands". These commands are interpreted from the doxygen
generator. Example of a Command is "\file" (or "@file"). You can
use one of the notations.


Here is an example file named Test.h:




/**
  * \file Test.h
  *
  * \author Hugo Habicht <hugo.habicht at osadl.org>
  *
  * \section history
  * \li 2007-09-30 created
  * \li 2007-10-01 changed first time
  * \li 2007-10-02 changed second time. This is an item that shows the 
use for
  * comments that cover more than one line.
  *
  */


/**
  * \fn void memcpy(void *dest, const void *src, size_t n);
  * \brief Copies bytes from a source memory area to a destination 
memory area,
  * where both areas may not overlap.
  *
  * \param[out] dest The memory area to copy to.
  * \param[in]  src  The memory area to copy from.
  * \param[in]  n    The number of bytes to copy
  *
  */
void memcpy(void *dest, const void *src, size_t n);



/**
  * \struct Test
  *
  * \brief This is a Test class.
  *
  * The Test class is used to demonstrate the use of the doxygen
  * documentation.
  *
  */
struct Test
{
   public:
     /** An enum type.
      *  The documentation block cannot be put after the enum!
      */
     enum EnumType
     {
       int EVal1,     /**< enum value 1 */
       int EVal2      /**< enum value 2 */
     };
     void member();   /**< a member function. */

   protected:
     int value;       /**< an integer value */
};



Instead of struct you may use the keyword class.
The member variables can be documented in different ways:

     /** an integer value */
     int value;

or

     int value;       /**< an integer value */


The "<" character shows that this documentation belongs to the left
variable


Hope this is enough to start.

Thomas