User Documentation
RAVL, Recognition And Vision Library
Ravl - Introduction - Documentation - Code

Documenting your code


Code is automatically documented using various specially-formatted comments embedded in the header files. For the impatient, an example header file highlighting the basic CxxDoc comments and variables is shown below.

Comments acknowledged by CxxDoc come in four varieties:

Symbol Description
//: "Blah...
//: ...blah."
Short descriptions are lines begining with "//:". Text in short description comments is concatenated to form a brief one line description of the class or member.
// "Blah...
// ...blah."
Detailed descriptions. Any C++ comments (lines beginning with "//") inside a class definition (or following a short description comment that preceeds the class definition) that do not begin with "//:" or "//!" are concatenated to form a detailed description of the class or member.
//!name: "Blah...
//!name: ...blah."
Special Comment Types. In addition to short and detailed descriptions, special custom comment types exist. The lines in these special comments start with "//!name:", where "name" can have different values shown below.
//! name=<value>Global Variables. Global variable definitions have the format. "//! name = <value>". They must occur OUTSIDE of any class declarations. There are three classes of variables: required, optional and automatic. The different global variables defined are described below. They apply to any items found in the header file following the comment in which they are declared.
Note that Variables have a space after the "!" whereas Special Comment Types do not. Also Variables will persist after their definition whereas Comments only exist at that point.

Please note that old C style comments between /* and */ are ignored when creating the documentation.

These comments are associated with declarations as follows.

  • The last short description (if any) before the Class (or typedef or macro etc) declaration is taken as the Class description. All detailed descriptions after that will be associated with the class (or typedef or macro etc).
  • All comments after each member declaration (functions, variables, typedefs etc) are taken as a description for that member of the class.
  • The const after a constant member function must be separated from the closing bracket by one space.
  • Special Comment Types

    These are the special comment types defined:

    Symbol Description
    //!classbugs: Use this to stress very dangerous bugs by inserting it after the detailed description of the class. It comes out in very big red font!
    //!param: This comment type is used to document the parameters in your member functions. The name of the parameter comes straight after it followed by a hyphen (-), and then the description of that parameter. To continue the description on another line you just have another !param: followed by a hyphen and then the rest of the description, as shown in the example header file below.
    //!bug: Use this to report less fundamental bugs associated to particular member functions. Insert it after the detailed description of the member function.
    //:- Use this to create sections in the documentation. A description of the section can follow in the normal way, as shown in the example header file below.

    Global Variables

    These are the required global variables defined:

    Symbol Description
    //! docentry = This variable tells CxxDoc where the Class goes in the Class Tree. Refer to the docentry web page for further details.
    //! userlevel = The userlevel can be one of the following:
    Basic - reserved for introductory RAVL classes.
    Normal - everyday RAVL classes.
    Advanced - for normal users, but require special knowledge or care in use.
    Develop : part of the implementation of something else and not really to be used directly.
    Obsolete - no longer used or have been replaced by something else, kept for backward compatibility.

    This is the only optional global variable defined:

    Symbol Description
    //! example = The example variable is used to specify a source file that uses the class for example purposes. Also don't forget to update the file:

         EXAMPLES =

    These are the automatic global variables defined. If you don't set them they are worked out automatically.

    Symbol Description
    //! file = The location of the header file.
    //! author = This is your username if you don't put anything explicitly.
    //! date = This is the time and date you created the class.
    //! lib = This is the library that the class is part of. This should be what a user would put in the USESLIBS line in a file if he wanted to use your class. It is case sensitive, and should be typed without quotes.
    //! rcsid = When you add the rcsid variable, you cut and paste it from here (or any other valid rcsid entry in any RAVL header file):

      //! rcsid="$Id: Ravl.Introduction.Documentation.Code.html,v 1.1 2001/07/06 12:34:55 vap-james Exp $"

    Once you check the file in, CVS will automatically fill in the right details - it doesn't matter what it said when you pasted it in. Each time you check in a new version it will automatically be updated. You should make sure that this entry is present in your header files. You need to add it the first time, after which it will be updated automatically.

    Example Header File

    This is a simple example showing the basic structure of a header file. It includes the expected comments and where they should be placed. There is a particular problem when using forward references. Placement of these are critical. In this example, the placement of the forward references are correct. For more details see Forward Referencing & Validity. For a real-life example in RAVL documentation see class StringC .

    #ifndef CLASSNAME_HH
    #define CLASSNAME_HH
    //! file =      "Ravl/ParentDir/ThisDir/ClassName.hh"   
    //! author =    "Author's Name"
    //! lib =       libname [no quotes]
    //! date =      "6/01/00"
    //! rcsid =     "$Id: Ravl.Introduction.Documentation.Code.html,v 1.1 2001/07/06 12:34:55 vap-james Exp $"
    //! userlevel = Normal
    //! example = [no quotes]
    //! docentry =  "Image.Image Representations"
    // Forward References (comment ignored since no //:)
    class A;
    class B;
    // ---------------------------------------------------------------------------
    // **********  Class ClassName  **********************************************
    // ---------------------------------------------------------------------------
    // (previous lines will be ignored - no preceeding //: )
    //: Brief description of the class
    // This class provides the facilities to do some stuff.<p>
    // These comments are aimed at the user!!!!!!<p>
    // As you can see, the detailed description can contain HTML markups to ensure
    // the appearance is as desired since the comments will be concatenated.
    //!classbugs: You can indicate that a class is buggy using this special comment
    //!classbugs: type. Make sure that you don't use !bug: here since it will then 
    //!classbugs: be associated with every member as well!
    class ClassNameC
    public :
      //: Default constructor
      //: Destructor
      //: Access Functions
       int AccessFn1(int id);
       //: Access function to return important number.
       //!param: id - Identification number
      //: Other Functions
      //  Detailed description of this section.
      MemberFunction(VectorC p, UIntT limit);
      //: Brief description of function
      //!param: p     - description of parameter
      //!param: limit - An very important threshold used to decide .....
      //!param:       - continuing desciption for the parameter `limit'
      // Detailed description of function which can
      // continue over many lines. Note that after the brief comment that they
      // can come in any order.
      //!bug: You can label a member as being buggy, eg not implemented or the
      //!bug: algorithm is rubbish etc.

    Forward Referencing & Validity

    There is a particular problem with documentation that is produced when forward references are included in header files. The class description must come AFTER all the forward references have been declared, i.e. there should be nothing between the class description and the definition of the class. A correct example was shown in the Example Header File section.

    Maintainer:Robert Crida, Documentation by CxxDoc: Tue Aug 13 10:00:52 2002