Documentation of Classes

Classes are collections of related functions (member functions) that can share and expose a persistent state by means of properties (variables). Member functions and properties can be documented with the techniques described in the previous two topics.

A member function or variable of a class must be given an @scope tag with the name of the class as the value. Thus binding the function or variable to the class definition.

The function that defines the class is the class constructor. These are documented like other functions in the class, the @scope tag illustrates that they belong to the class, and the @type tag shows that they return an instance of the class.

The fact that the functions and variables are related to each other by membership to the class makes it necessary to add an extra level of documentation that binds them and gives an overview of what the class is used for.

The class comment provides this overview. The class comment can be anywhere in the source code, but it is useful when placed before the class constructor comment. A class comment is created using an @class tag with the class name as the first word after the tag. A class comment for a persistent property bag is illustrated with the constructor comment.

/**
 * The PropertyBag class is used to store, retrieve, and access
 * a set of persistent properties.
 *
 * Properties are stored in a Shape, which must be a text label
 * or text box.
 *
 * Properties are key/value pairs, where both the key and the
 * value must be Strings.
 *
 * @class PropertyBag
 */


/**
 * The PropertyBag constructor creates a new PropertyBag 
 * instance.
 *
 *
 * If the in_objPersistenceShape parameter is not given the
 * PropertyBag is initialized to be empty.
 *
 * If the in_objPersistenceShape parameter is given, the
 * constructor attempts to load the property values from the
 * given shape.
 *
 * @param in_objPersistenceShape Shape an option parameter that
 * can be used to define the Shape to load the property values
 * from.
 * @type PropertyBag
 * @scope PropertyBag
 */
function PropertyBag(in_objPersistenceShape) {


   /**
    * Returns the value of the property identified by
    * in_strKey.
    *
    * If the PropertyBag does not contain a value for the
    * given key it will return null unless the optional
    * in_strDefaultValue parameter is supplied, in which
    * case that parameter value is returned.
    *
    * @param in_strKey String the key of the property 
    * whose value is to be returned
    * @param in_strDefaultValue String an optional default
    * value to be returned if the PropertyBag does not
    * contain the property identified by in_strKey.
    * @type String
    * @scope PropertyBag
    */
   function getProperty(in_strKey, in_strDefaultValue) {
      ...
   }
}

In the example, the @class tag in the first comment marks it as the class overview comment; the @type and @scope tags in the function comment for the PropertyBag function reference back to the @class value of the class overview comment, and mark the function as the class constructor. The comment for the getProperty function contains an @scope tag that links it to the PropertyBag class, but the @type tag shows it returns a string, so the documentation system knows it is a member function and not a constructor.