4. Documentation

Owned by Deepa Chavali
Last updated: Jan 24, 2013Version comment

 

4. Documentation

There are two main audiences for documentation:

  • Class Users
  • Class Implementors/Maintainers

Judiciously placed comments in the code can provide information that a person could not discern simply by reading the code. Comments can be added at many different levels.

  • At the program level, you can include a README file that provides a general description of the program and explains its organization. 
  • At the file level, include a file prolog that explains the purpose of the file and provides other information. 
  • In the header file, include a method prolog for all pure virtual methods. Add useful comments for class implementators and maintainers. 
  • In the source file, include a method prolog for all methods, other than pure virtual ones. Add useful comments for class implementators and maintainers. 
  • Throughout the file, where data are being declared or defined, it is helpful to add comments to explain the purpose of the variables.

Use of automated process to extract comments from the code can save developers time in generating documentation. Use Doxygen http://www.doxygen.org to automatically extract comments from the code and make it available on line for everyone to use. Any comments to be included in the documentation should follow the JavaDoc convention to mark a comment block. Set JAVADOC_AUTOBRIEF = YES in the Doxygen configuration file. If JAVADOC_AUTOBRIEF is set to YES in the configuration file, then JavaDoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line. The detailed descriptions follow after. (See Appendix B for commonly-used Doxygen commands)


 /**

    • brief description.*
    • detailed description.* */

You may use the following for a brief one line description:
/// one line brief description
Remember that comments beginning with '//' will NOT show up in the documentation.

4.1 Header File Prolog
  • All header files must begin with a header file prolog. 
  • PDL should not appear at the file level - it should be replaced by well-documented code. 
  • Since the main audience for the header is a user of the class (or utilities) and someone who may want to derive a class from this one, note any assumptions. 
  • Header file prologs should contain the following sections: (Since GMAT uses Subversion version control system (SVN) to control source code, a change history section should not be included. There is no reason to clutter up source files with duplicate information of that which is available from SVN.)


<SVN Keyword> <Class Name Banner> [for a class header] <Project Name> <Legal Tag> or <Copyright Notice> <Author> <Created> <Class Description> <Note> - optional 
The <SVN Keyword> should have:
$Id$ 
The <Class Name Banner> is the name of the class in the following form (include the namespace name, if applicable):
//----------------------------------------------------------------------- // Class Name //----------------------------------------------------------------------- 
The <Project Name> should have the following:
GMAT: General Mission Analysis Tool 
The <Legal Tag> should have the following:
**Legal* [A postprocessor will be used to insert the appropriate legal statement before release of the software]*
It may also include current contract information. 
The <Copyright Notice> should have the following:
h9.Text as specified and approved by team lead and Center legal authority 
The <Author> should have the following:
h9.Author: Your Name 
The <Created> should have the following:
Created: yyyy/mm/dd  
The <Class Description> should include general description of the class. Use the JavaDoc convention for marking a comment block. 

    • /**
    • class description.* */

The <Note> section should describe any information necessary for users of the class, including Requirement/Function Specification Reference. This field can be omitted if there are no notes for the user.
 
Example:

//$Id$ //----------------------------------------------------------------------------- // AngleUtil //----------------------------------------------------------------------------- // GMAT: General Mission Analysis Tool // // **Legal** // // Author: Linda Jun // Created: 2003/09/16 // /**

Declares AngleUtil which provides various angle computations.* */ //-----------------------------------------------------------------------------


4.2 Header File Pure Virtual Method/Function Prolog

For pure virtual methods, include a method prolog (as described in Section 4.4) in the header file, focusing on what is expected for the derived classes' implementations.

4.3 Source File Prolog
  • All source files must begin with a source file prolog.
  • Since the main audience for the source file is a maintainer, focus commentary on issues related to development and maintenance of the code.
  • Source file prolog format is the same as the header file prolog format (see Header File Prolog section).
4.4 Source File Method/Function Prolog
  • All methods and global functions (that are not pure virtual) declared in the header must have prologs in the source file. The prologs should focus comments on development issues and maintenance of the code. The prolog for a method/function appears just before the method's/function's implementation.
  • Each prolog should describe the method/function clearly and concisely as to its purpose, inputs, return value (if any), and possible exceptions or abnormal conditions.
  • The exception section should list exceptions thrown in the class. This field can be omitted if no exceptions thrown.
  • Notes about the ownership and deletion responsibilities for pointer arguments can be included in the argument description. 
  • The @see section can be used to point the developer/maintainer to the method prolog in the parent class, in lieu of listing all prolog elements here. 
  • It is useful to list expected units for input parameters and the return value, when applicable. 
  • The source file function prolog should contain the following information:


//----------------------------------------------------------------------------- // function signature //----------------------------------------------------------------------------- /**

brief description of this function.*

detailed description of this function if any.* ***

@param* - if applicable

@return - if applicable*

@exception - if applicable*

@see - if applicable*

@note - if applicable* */ //-----------------------------------------------------------------------------
Example:
//----------------------------------------------------------------------------- // bool TranslateToMJ2000Eq(const A1Mjd &epoch, const Rvector &inState, // Rvector &outState) //----------------------------------------------------------------------------- /**

This method translates the input state, in "this" axisSystem to the MJ2000Eq*

axisSystem.* ***

@param epoch epoch for which to do the conversion.*

@param* inState input state to convert.

@param* outState output (converted) state. ***

@return true if successful; false if not.* *** */ //----------------------------------------------------------------------------- bool CoordinateSystem::TranslateToMJ2000Eq(const A1Mjd &epoch, const Rvector &inState, Rvector &outState)

4.5 Comments in General

The C++ comment indicator(//) should be used exclusively, except where comments are intended for documentation. In that case, the comments should use Doxygen style. 

  • Do not include Program Design Language (PDL). Instead, care should be taken to clearly, yet succinctly comment the code. i.e. put a block comment before each major section of code, document variable declarations where needed, refer the reader to specifications or documents for further information if appropriate, etc. 
  • Include units in comments for variable declarations, if units are not included in the variable name.

Example:

Vector3 initialPosition(0.0,0.0,0,0); // initial position vector in km

  • Line up comments for declared variables. 
  • In particular, when coding from a formal specifications document, make sure to include the reference in the file prolog; and if coding a specific algorithm, include a reference to the source of the algorithm in the function prolog/epilog (and possibly in the file prologs as well). 
  • It is also useful when coding from a formal specification, to include commentary, at each step, specifying the step number or brief description from the specifications, to make it easier for code-readers to follow. In cases where equation or section numbers may later change, including a brief description is preferable to referencing specific sections, page numbers, or equation numbers. However, comments should not be too verbose or restate the obvious.

Example

// Compute precession (Vallado, Eq. 3-56) Real zeta = ( 2306.2181*tTDB + 0.30188*tTDB2 + 0.017998*tTDB3 ) *RAD_PER_ARCSEC; Real Theta = ( 2004.3109*tTDB - 0.42665*tTDB2 - 0.041833*tTDB3 ) *RAD_PER_ARCSEC; Real z = ( 2306.2181*tTDB + 1.09468*tTDB2 + 0.018203*tTDB3 ) *RAD_PER_ARCSEC;
// Compute trigonometric quantities Real cosTheta = Cos(Theta); Real cosZ = Cos(z); Real cosZeta = Cos(zeta); Real sinTheta = Sin(Theta); Real sinZ = Sin(z); Real sinZeta = Sin(zeta);
// Compute Rotation matrix for transformations from FK5 to MOD // (Vallado Eq. 3-57) Rmatrix33 PREC; …