Isis 3 Documentation

Introduction | Mandatory Commands | Useful Commands | Example Header | Example Implementation | HTML Quick Reference

Mandatory is a strong word we will define here to mean use it if it applies. Many tags will always be used, such as $Revision$ for files and @ingroup for classes. Other tags may not always be applicable, such as @return and @param for functions.

Descriptions do not require a special tag. Simply write text and make sure for blocks there's a blank line before and after the description:

/**
 * @brief Get my integer
 *
 * myMethod is a simple function for returning
 * my integer stored in this data structure.
 *
 * @return (int) The current value of my integer.
 */
int myMethod () {
  return myInteger ;
}

Syntax notes: Within the list of the following commands, arguments will be outlined in < >s, []s, {}s, and ()s. Below is a list of their meanings:

• <argument>: Signifies a one-worded argument. Any comments after the initial word will be either ignored or used as comments, depending on the command.
• [argument]: Indicates an optional one-worded argument.
• (argument): Indicates a multi-worded argument that is not a description or comment block
• {argument}: Indicates a description or comment stream.

Do not use any of these indicators within your doxygen comment blocks. They are merely for organization of this document only.

Top

Files:

@file: Required to start a file documentation block.

Disclaimer: Use the following disclaimer in the @file block of every file:

Unless noted otherwise, the portions of Isis written by the USGS are public domain. See individual third-party library and package descriptions for intellectual property information, user agreements, and related information.

Although Isis has been used by the USGS, no warranty, expressed or implied, is made by the USGS as to the accuracy and functioning of such software and related material nor shall the fact of distribution constitute any such warranty, and no responsibility is assumed by the USGS in connection therewith.

For additional information, launch $ISISROOT/doc/documents/Disclaimers/Disclaimers.html in a browser or see the Privacy & Disclaimers page on the Isis website, http://isis.astrogeology.usgs.gov, and the USGS privacy and disclaimers on http://www.usgs.gov/privacy.html.

$Revision$: Enters the CVS version of this file into the documentation. CVS will replace this string with the full version string when the file is checked in. For example, the CVS version of this document is $Revision: 1.1.1.1 $.

$Date$: Enters the CVS last modification date of this file into the documentation. CVS will replace this string with the full last modification date when the file is checked in. For example, the CVS last modification date of this document is $Date: 2006/10/31 23:18:12 $.

Notes

Additional documentation: A brief and/or long description, history, or other information is left to the discretion of the programmer.

Other CVS tags: $Id$ and other CVS tags may be used at the taste and discretion of the programmer.

Top

Classes:

Give an overall description of the class. Does it represent a particular data structure (e.g. binary tree) or emulate the behavior and attributes of a real world object (e.g. camera) or concept (e.g. vector)?

Writing Inline Examples with @code and @endcode: Examples should always be provided to illustrate the setup and intended use of a class. Include one or more brief examples in your documentation, using the @code to start the example and @endcode to end the example. Do not escape special characters like <, >, and & inside a @code/@endcoe block - your code snippet will be parsed and special characters properly rendered for you.

Linking to Examples in Other Isis Objects or Applications: Whenever possible, point out working Isis sourcecode where your object is in heavy and thorough use, such as a class or application containing your object or a a class inheriting your object. In the web page output, names of files and classes in your descriptions are automatically linked to the appropriate documentation. Simply write a sentence that contains the class or file names you wish to link to with a bit of explanation, such as in the following snippet from the Statistics class documentation:

* For an example of how the Statistics object is used in %Isis, see the
* Histogram object (inherits from Statistics) and the stats application,
* stats.cpp (uses the Statistics child class Histogram).

In the resulting web page output, Statistics, Histogram, and stats.cpp will all be linked to pages about those classes and file. The percent sign (%) in '%Isis' prevents the word Isis from being linked to the Isis namespace documentation.

@author { Author }: Always use original author(s), with modifiers noted in @history.

@bug { bug description }: Use for noting bugs. Remove the bug documentation when the bug is fixed, and make a note in a @history entry.

@deprecated: Indicates a deprecated entity in a documentation block.

@ingroup(<groupname>[<groupname> <groupname>]): Categorize this class as belonging to a particular group of Objects. The class documentation will be linked in the group's page (identified by <groupname>). Groups are listed in the Modules section of the Isis documentation, and defined by the isisDoxyDefs.doxydef file.

@whatsnew { date } { paragraph describing new features }: Description of a new feature of this class that users of your object will find interesting. Keep it exciting, simple, and brief.

Internal Class Documentation

@internal: to start a section of internal documentation put @internal on its own line in your documentation block. Everything between the @internal tag and the end of the block will be marked as "not for public consumption." Internal documentation will not appear in the API, only in the Programmers' Reference.

@todo and @history should always be placed in the internal section of the documentation.

@todo { paragraph describing what is to be done }: Notes a lien, or item needing to be done. When it's done, the entry should be removed and a @history entry should be added.

@history YYYY-MM-DD <author> { description of change } : Make a note of the who, when, and what of a modification to the class.

Top

For Methods:

Methods are documented where they are implemented. Inline methods will be documented in the header, others in the implementation file.

Write a wonderful description explaining the use of the method. Information describing its implementation, such as algorithms, design decisions, etc. can be placed in an @internal section at the end of the documentation block. Parameters, return value, and exceptions thrown are documented in their own section in the method's documentation block.

Use the following tags as needed to complete your desription.

@author { Author }: This is only needed if the method author is not the author of the method's scope (e.g. Bob added a member function to Ted's class). Always use original author(s), with modifiers noted in @history.

@bug { bug description }: Use for noting bugs. Remove the bug documentation when the bug is fixed, and make a note in a @history entry.

@deprecated: Indicate a deprecated function.

@param<[in|out|in,out]> <parameter-name> {(type) parameter description}: Describe a parameter for the function with name <parameter-name>, followed by the parameter type, then a description. The @param command also has a mandatory attribute specifying direction of the attribute, [in] or [out], or [in,out] for both.

@return (type) {description}: Describe the return value of a method.

@throws <exception-object> { description }: Desribe the exception of type exception-object thrown by this method.

@relates <name>: Indicate this function is related to the entity indicated by name. Useful for documenting non-friend functions that are nevertheless strongly coupled to a certain class. This tag will cause this method's documentation to be included in the documentation indicated by name.

Example:

/*!
* A String class.
*/
class String {
  friend int strcmp(const String &,const String &);
};

/*!
* Compares two strings.
*/
int strcmp(const String &s1,const String &s2) {...}

/*! @relates String
* A string debug function.
*/
void stringDebug() {...}
  

@see { references }: List cross-references to classes, functions, methods, variable, files, or URL may be specified. Two names joined by either :: or # are understood as referring to a class and one of its members. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method name.

Internal Documentation

@internal: Start a section of internal documentation by putting @internal on its own line in your documentation block. Everything between the @internal tag and the end of the block will be marked as "not for public consumption." Internal documentation will not appear in the API, only in the Programmers' Reference.

@todo and @history should always be placed in the internal section of the documentation.

@todo { paragraph describing what is to be done }: Note any liens, or items needing to be done. When it's done, the entry should be removed and a @history entry should be added.

@history YYYY-MM-DD <author> { description of change } : Make a note of the who, when, and what of a modification to the class.

Top

Variables:

For most variables, a short one-lined description will suffice. For longer descriptions, use a description block (described in the Basics section of this document). Variable declarations are often one of the places where programmers prefer to place their documentation on the same line after the declaration. In the following example, note the use of the left angle bracket to start documentation that follows the value, and this notation can be used for both single and block documentation.

int    counter ;   //!<  An iterator that tracks how often this instance has been touched
float  value   ;   //!<  The value stored by this data structure
String title   ;   /**!< The title, or name, of the value.
                    *    The title follows the standards outlined
                    *    in the design document available on the
                    *    mission website.
                    */
  

Use @internal, @history, @whatsnew, @author, @todo, and other tags if needed.

Top

For Other User Defined Types:

Aside from classes, most user defined type declarations need only a short one-lined description For longer descriptions, use a description block (described in the Basics section of this document).

In all cases, use @internal, @history, @whatsnew, @author, @todo, @deprecated, and other tags if needed.

Enumerations: A general description is required for all enum declarations, and enumeration value descriptions should be used as necessary. In the following example, note the use of the left angle bracket to start documentation that follows the value, and this notation can be used for both single and block documentation.

/**
 * This enum is a set of red, blue, and green values of a specified pixel.
 */
enum Colors {
    Red,    //!<  The "red" value of the pixel.
    Blue,   //!<  The "blue" value of the pixel.
    Green   /**!< The "green" value of the pixel.
             *    Green is a very special portion of
             *    the visible EM spectrum, so more
             *    documentation is being provided.
             */
};
  

Structures: A general description is required for all stuct declarations and the variables they contain. In the following example, note the use of the left angle bracket to start documentation that follows the value, and this notation can be used for both single and block documentation.

/**
 * This structure holds a name-value pair
 */
struct NamedFloat {
  float  value   ;   //!<  The value stored by this data structure
  String name    ;   /**!< The of the value.
                      *    The name follows the standards outlined
                      *    in the design document available on the
                      *    mission's website.
                      */
};
  

Type Definitions: A general description is required for all type definition declarations. Note in the example below the use of the @internal tag to add a little extra information for other programmer's to understand why the types were defined (i.e. explains the design decision).

/**
 * A set of data types to represent various monetary units.
 *
 * @internal This typedef was created for the purpose of increasing code readability.
 */
 typedef int Pounds, Shillings, Pennies, Dollars, Cents;
  

@internal: Use this in any documenation block where you wish to add internal documentation, such as comments regarding design, @history, @todo, and so forth. All documentation after the @internal tag and before the end of the documenation block will appear in a section of the Programmer's Documentation titled "For internal use only."

Document History