
Examples of the formatting of code comments that are intended to become part of the autogenerated  API documentation.


A FUNCTION:

/**
 * Count the number of arguments on the attribute's dynamic argument list.
 *
 * (a detailed description could go here)
 *
 * @param attribute  pointer to the Attribute object to analyse
 * @return           int specifying the number of arguments;
 *                   a negative integer is returned if for any argument
 *                   on dyn.arglist, the type is equal to ATTAT_VAR
 */
int
nr_of_arguments(Attribute *attribute)
{
(...)








A STRUCTURE:


/**
 * Underlying structure for the CorpusProperty object-pointer type.
 * The structure takes the form of a linked-list entry.
 */
typedef struct TCorpusProperty {
  /**
   * A string specifying the property in question.
   */
  char *property;
  /**
   * A string containing the value of the property in question.
   */
  char *value;
  /**
   * Pointer to the next entry in the linked list.
   */
  struct TCorpusProperty *next;
(...)





A STRUCTURE, USING THE ALTERNATIVE SAME-LINE FORMAT FOR MEMBERS


/**
 * Contains information on a loaded corpus.
 *
 */
struct TCorpus {
  char *id;          /**< a unique ID (i.e., the registry name identifying the corpus to the CWB) */
  char *name;        /**< the full name of the corpus (descriptive, for information only) */
  char *path;        /**< the ``home directory'' of the corpus  */
  char *info_file;   /**< the path of the info file of the corpus */

  CorpusCharset charset;           /**< a special corpus property: internal support for 'latin1' to 'latin9' planned */
(...)



