Source Code Documentation

OpenCLAWS source files make use of Javadoc notation for files and functions. Reference documentation is automatically generated using Doxygen. This page describes the source code documentation standard for OpenCLAWS.

General

All new source files should contain the following comment block at the top of the file:

/**
 * OpenCLAWS - Account/Identity/Computer Management
 * Copyright (C) 2009 The OpenCLAWS Project
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */

Existing source files already have the above header. In the case of CLAWS source files, RIT's header is to remain intact.

The primary source file in a group will need to define the Doxygen module.

/**
 * @defgroup    helloworld Example module
 * @ingroup     modules
 */

Each file will also contain a brief description, the name of group the file belongs to, the file name, and the list of contributing authors. For example:

/**
 * @brief       Example module
 *
 * @ingroup     helloworld
 * @file        moduleHello.c
 *
 * @author      Bob Carroll (bob.carroll@alum.rit.edu)
 */

Note that @contrib is not supported. Contributors should use @author.

Function Definitions

All functions should have a comment block immediately above the definition.

 /**
  * db_score_args()
  *
  * Computes the max score on the given identity.
  *
  * @param id -- the input identity XML node
  * @param res -- a pointer to the max score float
  *
  * @returns
  *      ERROR_OK: success \n
  *      ERROR_ORC_ERROR: Oracle error
  */
 int db_score_args( xmlNode *id, float *res )
 {
   ...
 }

In the above example, the function name is shown first followed by a brief summary of what the function does. The argument list includes a description of each argument. Finally, a list of return codes with a short explanation end the block.

When a function doesn't have arguments or a return value, it would look like this:

 /**
  * db_release_commit()
  *
  * Releases open database handles and commits work.
  */
 void db_release_commit()
 {
   ...
 }