Rules and Standards

Checklist for CAA V5 C++ Interface and Class Documentation Rules

How to make sure that the comments in your header files are correct
Quick Reference

Abstract

This article gives you a series of check lists to ensure that your exposed objects are correctly documented.


For Each L1 File

For each "L1" file, check the following:

File Check List
Copyright is set to //COPYRIGHT DASSAULT SYSTEMES 2001
@CAA2Level is set to L1
@CAA2Usage is appropriately set to U1/U2/U3/U4/U5
If @CAA2Usage is set to U4, the adapter class name is provided

[Top]

For Each Class or Interface

For each class or interface, check the following:

Class or Interface Check List
Comment is just above the class declaration
Short role is shorter than a line and ends with a period
Role describes the actual mission (what it does, not how it does)
@href and @see tags refer to "L1" entities in the same framework or in prerequed frameworks

[Top]

For Each Constructor

For each constructor, check the following:

Constructor Check List
Short role is written as "Constructs a xxx.", except for a copy constructor for which it is "Copy constructor"
Short role is shorter than a line and ends with a period
Role, if any, gives valuable additional information compared to the short role
@param tag is used for each parameter and matches dummy argument in method signature
Legal values named field is used wherever applicable in @param tag, and describes default values
Cyclic reference named field is used wherever applicable
Cyclic reference named field uses standard sentences
Lifecycle rules deviation named field is used wherever applicable
Lifecycle rules deviation named field uses standard sentences
@href and @see tags refer to "L1" entities in the same framework or in prerequed frameworks

[Top]

For Each Method or Global Function

For each method, check the following:

Method or Global Function Check List
Short role begins using an action verb
Short role is shorter than a line and ends with a period
Role, if any, gives valuable additional information compared to the short role
Role, if any, focuses on "what", not on "how"
Precondition named field is used wherever applicable and describes the calling context
Postcondition named field is used wherever applicable and describes the returned context
@param tag is used for each parameter and matches dummy argument in method signature
In case method returns under a 'weak' type (e.g. CATBaseUnknown) a more specific type (e.g. CATIEdit), the specific type is documented as the real return type of the argument.
Legal values named field is used wherever applicable in @param tag, and describes default values
Cyclic reference named field is used in @param tag wherever applicable
Cyclic reference named field uses in standard sentences
Lifecycle rules deviation named field is used in @param tag wherever applicable
Lifecycle rules deviation named field uses standard sentences
@return tag is used for returned values, except if the method is a "getter"
Legal values name field is used inside @return tag
@exception tag is used wherever applicable
@href and @see tags refer to "L1" entities in the same framework or in prerequed frameworks

[Top]

For Each Enumeration

For each enumeration, check the following:

Enumeration Check List
Short role is written as a qualified name
Short role is shorter than a line and ends with a period
Role, if any, gives valuable additional information compared to the short role
@param tag is used for each enum constant and matches the enum constant value name
@href and @see tags refer to "L1" entities in the same framework or in prerequed frameworks

[Top]

For Each Operator

For each operator, check the following:

Operator Check List
Short role is standard according to operator's type
Short role is shorter than a line and ends with a period
Role, if any, gives valuable additional information compared to the short role
@param tag is used for each parameter and matches dummy argument in method signature
@href and @see tags refer to "L1" entities in the same framework or in prerequed frameworks

[Top]

For Each typedef

For each typedef, check the following:

Typedef Check List
Short role begins with "Type to use with" /  qualified name
Short role is shorter than a line and ends with a period
Role, if any, gives valuable additional information compared to the short role
@href and @see tags refer to "L1" entities in the same framework or in prerequed frameworks

[Top]

Checking mkman Messages

Run mkman for the C++ classes and interfaces of your framework.

Check that mkman doesn't issue errors.

When mkman runs, errors are issued as lines beginning with # mkmdocman-ERROR and a short explanation of the error found.

html files are generated in the Doc\generated\refman directory located in your workspace root directory. Doc is at the same level than your framework directories.

refman contains:
  • A directory and a file per framework:
    • The directory contains a html file for each existing header file, that contains the documentation extracted from the header file and that has the same name than the header file, but is suffixed with htm.
    • A file per framework that contains the framework object list
  • Three files:
    • AllNames.htm contains an index of all the classes,  methods, enums, etc..
    • main.htm contains the list of frameworks
    • tree.htm contains the classes arranged using their inheritance tree structure

Using your favorite browser, navigate through these files, starting with main.htm.

Framework Page Check List
Check that all L1 interfaces are listed in Interface Index
Check that all L1 classes are listed in Class Index
Check that all L1 exceptions are listed in Exception Index
Check that all L1 enum are listed in Enumerated Type Index
Browse all files

Check the index in AllNames.htm that quickly shows if you forgot the period at the end of the short roles.

[Top]

Copyright © 2000, Dassault Systèmes. All rights reserved.