Doxygen comment guidelines

From Ekiga

Contents 1 Why 2 Guidelines 2.1 General 2.2 Files 2.3 Structures 2.4 Variables 2.5 Functions

Why

The code documentation of Ekiga are plain comments in the source files. To increase documentation quality, it would make sense to add some Doxygen compatible comments. This guide tries to "standardize" the commenting, as Doxygen itself knows a load of different syntax.

Please see Doxygen commenting tutorial before doing anything else. This Wiki page is just a summary and a common syntax guideline, no doxygen documentation.

Guidelines

General

I suggest the JavaDoc style. It takes a "!" as designator after a normal C/C++ comment begin. This is followed by specific keywords. Here's a selected list of hopefully useful keywords. There will be more verbose examples below.

• \author: An author's name. Not only limited to a \file section
• \brief: a brief description of something. Will be included in overviews.
• \date: guess.
• \fn: a function declaration. Syntax: \fn C_FUNCTION_DECLARATION. Only needed when your comment for a function is not directly before or behind the function.
• \param: a parameter description, inside a \fn block. Syntax: \param NAME DESCRIPTION, e.g. \param main_window* a pointer to the main window
• \struct: a struct documentation. Syntax: \struct NAME [HEADER_FILE] [HEADER_NAME]

Also see the GeneralCodingGuidelines, but most of these shouldn't be needed with Doxygen commenting.

Files

 /*!\file gmcontacts.h
  *\brief header file for gmcontacts API
  *
  * This includes the API for the GmContact and GmAddressbook (...lobger description...)
  *\author Damien Sandras
  */

Multiple \author statements are possible. General keywords like \warning or \date can be used here, too.

Structures

Variables

Variables of any kind can be documented "on the fly". A verbose example from gmroster.h below. The !\struct keyword isn't needed, as Doxygen sees it on the context.

 /*!\struct _GMRoster    // <---- \struct is not needed, the following thing *is* a sctruct!
  * \brief GMRoster instance structure
  * \see GMRoster
  */
 struct _GMRoster
 {
   GtkTreeView treeview;
   /*!< GtkTreeView of the GMRoster */
 
   GSList* contacts;
   /*!< private list of contacts that the GMRoster manages */
 
   GdkPixbuf * icons [CONTACT_LAST_STATE];
   /*!< icons corresponding to the contact status, default: all NULL */
 
   gchar* statustexts [CONTACT_LAST_STATE];
   /*!< status texts corresponding to the contact status, default: all NULL */
 
   gchar* unknown_group_name;
   /*!< the string to be used when a contact has no category set, default: "unknown" */
 
   gchar* roster_group;
   /*!< the string to be used to identify if a contact has to be displayed
    * at all, default "Roster" */
 
   gboolean show_offlines;
   /*!< indicator weather to show "offline" contacts or not, default: TRUE */
 
   gboolean show_groupless_contacts;
   /*!< indicator weather to show contacts without any category or not, default: TRUE */
 
   gboolean show_in_multiple_groups;
   /*!< indicator wheather to show a contact in all its groups or only the first, default: FALSE */
 };

Functions

 /*!\fn gm_groups_editor_get_commalist (GmGroupsEditor *groups_editor) // <--- also context aware, usually \fn not needed
  * \brief retrieve the actual list of selected groups as a comma separated list
  *
  * Returns all selected groups as comma-separated GmContact like string. If no
  * groups are selected, the returned string is "" (empty string), not NULL.
  * \param groups_editor a GmGroupsEditor
  * \return the comma-separated selected groups in a string
  */
 gchar *gm_groups_editor_get_commalist (GmGroupsEditor *);