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.