Documenting RAPID IDL Source

The purpose of the IDL Source Documentation is to describe the Modules, Constants, and Data Types defined by the RAPID system.

A number of different documentation styles and directives are used to control where and how documentation is presented. In general, the RAPID team uses three different styles of documentation mark-up and two different directives to control the Doxygen documentation and source code generation processes. The following table describes the files RAPID generates with Doxygen:

Descriptive Page

This page contains descriptive information about RAPID. For example, the page you're reading now is a Descriptive Page.

Source Page

An HTML page containing a representation of the source code file, cross-referenced to definitions in other Source Files. Follow this link, AccessControlState.idl, then follow the Go to the source code of this file link.

Generated Source File

The RAPID IDL sources files are used to generate language-specific source code in Java and C++.

A table of styles and directives is shown below, with additional explanation of these items in the following sections.

Style or Directive	Example	Appears In
		Descriptive Page	Source Page	Generated Source File
Special documentation block	/** … */	Yes	No	No1
C-style documentation blocks	/* … */	No	Yes	No1
C++-style documentation blocks	// …	No	Yes	No1
Copy declaration directive	//@copy-declaration …	No	No	Yes
Copy C declaration directive	//@copy-c-declaration …	No	No	Yes

Notes: ¹The documentation block will be copied into a Generated Source File if and only if a copy directive is used.

Documenting IDL Source for a Descriptive Page

JavaDoc-style documentation blocks (also known as "Special documentation blocks" in Doxygen) are processed by Doxygen into a Descriptive Page for browser-based viewing. Special documentation blocks are not copied into a Source Page, nor are they copied into a Generated Source File unless accompanied by a copy directive.

/**
 * \defgroup idlfiles IDL Files
 *
 * \brief The RAPID specification for messages and methods is defined in IDL files.
 */

Example: A Special documentation block containing Doxygen directives for a Descriptive Page.

Documenting IDL Source for a Source Page

When creating a Source Page, Doxygen will remove Special documentation blocks—which contain either directives for a Descriptive Page or for IDE-accessible documentation like JavaDoc—while including C- and C++-style comments. C- and C++-style comments will not be placed in a Generated Source File unless preceded by a copy directive.

/*
 * Copyright  2009 United States Government as represented by the
 * Administrator of the National Aeronautics and Space Administration.
 * All Rights Reserved.
 */

Example: This C-style documentation block will only appear appear in a Source Page.

C- and C++-style comments are carried into the the Source Page, and will be placed a Generated Source File if preceded by a copy directive. This style of comment is not usually accompanied by a copy directive because these comments are not made available to the programmer through references in their IDE.

/* C-style comment */
// C++-style comment

Example: These C- and C++-style documentation blocks will only appear in a Source Page.

Documenting IDL Source for a Generated Source File

The rtiddsgen program requires special directives to copy documentation into a Generated Source File in a way that is useful to a programmer working in a IDE such as Eclipse that provides interactive documentation for references. The @copy-declaration directive copies the text into the file where the type is declared (<type>.h for C and C++, or <type>.java for Java). The //@copy-c-declaration directive is identical to //@copy-declaration, except that it applies only to generated C and C++ code.

In RAPID IDL files, detailed documentation is written in a JavaDoc-style documentation block that will not appear in a Source Page, but will appear in a Descriptive Page alongside the element it describes. The documentation will also appear in a Generated Source File because of the presence of the copy directives.

//@copy-declaration /**
//@copy-declaration  * AccessControlState is a recurring message type that provides information
//@copy-declaration  * about who has control of a specified asset and who has requested control
//@copy-declaration  * of that asset.
//@copy-declaration  */

In RAPID IDL source files, brief member documentation is written before the member using this format:

//@copy-declaration /** Specifies agentId that currently controls the asset. */
public String32 controller;

Doxygen then copies the documentation into a Generated Source File in a way that is compatible with both Java and C++. The documentation in a JavaDoc-style documentation block will not appear in any Descriptive Page unless you copy it manually into a Special documentation block.