Rules and Standards |
Checklist for CAA V5 C++ Interface and Class Documentation RulesHow to make sure that the comments in your header files are correct |
|
Quick Reference |
AbstractThis article gives you a series of check lists to ensure that your exposed objects are correctly documented. |
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, 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, 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, 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, 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, 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, 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]
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:
|
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.