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.
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. |
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 defs.mk file:
EXAMPLES = myexample.cc
|
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 defs.mk
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.
|
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 = example.cc [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 :
ClassNameC();
//: Default constructor
~ClassNameC();
//: 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.
};
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.