Rules and Standards

What Do You Need to Document?

Each of the following entity declared as L1 must be documented.

• Class
• Interface
• Constructor
• Method
• Global function
• Macro
• Collection
• Enumeration
• Operator
• Structure
• Class or structure data members
• typedef

This applies to L1 entities that are located in the PublicInterfaces directories of the exposed frameworks. This includes members declared as public, and for classes that can be derived, members declared as protected.

[Top]

How Do You Document?

Interfaces, classes, and all the stuff they include, are documented thanks to information enclosed into specific comments inserted in the header files. The C++ statements and the comments are then processed to produce an organized set of html files in which you and the users of your interfaces and classes can navigate. These comments are as follows:

/**
 * This is a comment.
 */

They must begin by /** and end by */. Each intermediate line must begin by a leading *. Never use such a comment for any other purpose than documentation, otherwise your internal comments will be processed and clearly readable, and moreover may pollute automatically generated lists and index.

A comment must be placed just before the line containing the declaration of the class, interface, method, etc., it is intended to describe.

/**
 * Base class for creating and for implementing interfaces.
 * CATBaseUnknown supplies the infrastructure and the basic mechanisms
 * to create interface abstract classes and to manage interface pointers.
 */
class ExportedByJS0CORBA CATBaseUnknown : public IDispatch
{
...

[Top]

A Simple Sample

[Top]

Writing Comments

You will find below some tips to write comments for classes, interfaces, constructors, methods, global functions, enums, operators, struct, data members, and typedef.

[Top]

Writing Class Comments

Do:

• Begin with the short role. End it using a period
  • Write short such as "Class to xxx", or "Class representing xxx" for a class to use as is.
  • Write "Base class to xxx" for a class to derive.
• Write the class role, beginning with Role. This describes the class mission, for what purpose you have created it. It can also include a brief description of the class usage, namely using its main methods.
• Other comments Usage?, On what it relies?
• You can add a See also section to create hyperlinks to objects that are related to the class.

Don't:

• Forget the period at the end of the short role
• Describe how the class is implemented
• Create hyperlinks to the base classes, since the class inheritance tree is automatically built with such hyperlinks

Refer to the following examples:

[Top]

Writing C++ Interface Comments

Do:

• Begin with the short role. End it using a period
  • Write short roles for C++ interfaces: "Interface to xxx", "Interface for xxx", or "Interface representing xxx"
• Write the interface role, beginning with Role. This describes the interface mission, for what purpose you have created it. It can also include a brief description of the interface usage, namely using its main methods.
• If the usage is U4, give the adapter class to use.
• Leave room for flexibility if the interface must be fully implemented
• You can add a See also section to create hyperlinks to objects that are related to the interface.

Don't:

• Forget the period at the end of the short role
• Describe how you would have implemented the interface
• Create hyperlinks to the base interfaces, since the inheritance tree is automatically built with such hyperlinks

[Top]

Writing Constructor Comments

Do:

• Begin with the short role. End it using a period
• Write "Constructs a xxx." For a constructor with parameters, try to qualify these parameters while keeping a short sentence. For example, write "Constructs a 3D point given its coordinates.", or "Constructs a smart interface pointer from a pointer to CATBaseUnknown."
• Write "Constructs an empty xxx." for a default constructor (a constructor without parameters)
• Write "Copy constructor." for a copy constructor
• Write additional comments if the short role is not enough
• Build the list of parameters using the @param tag. Follow the CNext rules for input, output, and input/outpout parameters, and CNext parameter naming conventions.

  Reminder of CNext rules and naming conventions

  • The parameters of member functions must all be named. The name is an important source of information for developers with regards to the meaning of the function.
  • The parameters of member functions belong to one these three categories: in, out or inout. To make this classification more explicit, the name of the parameter must begin with the prefix 'i' (in), 'o' (out) or 'io' (inout). The first character of the name must be uppercase (ex: iIndex, oElement). See Lifecycle Rules for parameter allocation.
• Use Legal values for each parameter, if this is meaningful and describe the default value, if any
• Use Cyclic reference for each parameter if it is an interface pointer that the constructor keeps as a data member
• Use Lifecycle rules deviation for each each parameter for which the constructor is in deviation with respect to the CNext lifecycle rules for objects, interface pointers, and smart pointers
• If needed, you can add a See also section to create hyperlinks to objects or methods that are related to the constructor.

Don't:

• Forget the period at the end of the short role
• Let types alone in constructor signatures. Put dummy arguments instead and use them with @param
• Create hyperlinks to the classes or enums used as types for parameters, since these links are automatically set up

Refer to the following examples:

[Top]

Writing Method Comments

Do:

• Begin with the short role. End it using a period
  • Begin the short role using an action verb, such as Analyzes, Processes, Adds, Computes, etc.
  • Use Returns for a getter, that is a method that simply returns a value
  • Use Retrieves for a method whose role is to return a value using one of its parameters, even if it has a returned value
• Write additional comments, if the short role is not enough, in the Role section
• Build the list of parameters using the @param tag. Follow the CNext rules for input, output, and input/outpout parameters, and CNext parameter naming conventions.

  Reminder of CNext rules and naming conventions

  • As a general rule, any method that gets a pointer to CATBaseUnknown, either as a returned value or as an output parameter, must describe the expected interface or class that stands at the end of the pointer in order that the method caller can efficiently use this pointer
  • The parameters of member functions must all be named. The name is an important source of information for developers with regards to the meaning of the function.
  • The parameters of member functions belong to one the these three categories: in, out or inout. To make this classification more explicit, the name of the parameter must begin with the prefix 'i' (in), 'o' (out) or 'io' (inout). The first character of the name must be uppercase (ex: iIndex, oElement). See Lifecycle Rules for parameter allocation.

  Begin an argument definition using the definite article The. For example, write The point coordinates, or The dialog agent. You can use A instead of The if there is a part of indetermination, such as A pointer to the IUnknown interface, if the pointer is not explicitly defined or used in the description beforehand.

• Use Legal values for each parameter, if this is meaningful and describe the default value, if any
• Use Cyclic reference for each parameter if it is an interface pointer that the method keeps as a data member
• Use Lifecycle rules deviation for each each parameter for which the method is in deviation with respect to the CNext lifecycle rules for objects, interface pointers, and smart pointers
• Use Overloads to describe several prototypes of the same method
• Use Overrides to redefine an inherited method
• If needed, you can add a See also section to create hyperlinks to objects or methods that are related to the method
• Add a Returns section using the @return tag if the method returns a value, except for a getter
• Use Legal values to describe each returned value, including each HRESULT value
• Add a Throws section using the @exception tag if the method throws an exception
• Set hyperlinks to the error classes thrown as exceptions thanks to the @href tag

Refer to interfaces or global functions for HRESULT examples.

Don't:

• Forget the period at the end of the short role
• Let types alone in methods signatures. Put dummy arguments instead and use them with @param
• Create hyperlinks to the classes or enums used as types for parameters, since these links are automatically set up

[Top]

Writing Global Function Comments

Do:

• Begin with the short role. End it using a period
  • Begin the short role using an action verb, such as Creates, Processes, Adds, Computes, etc.
• Write additional comments, if the short role is not enough, in the Role section
• Build the list of parameters using the @param tag. Follow the CNext rules for input, output, and input/outpout parameters, and CNext parameter naming conventions.

  Reminder of CNext rules and naming conventions

  • The parameters of member functions must all be named. The name is an important source of information for developers with regards to the meaning of the function.
  • The parameters of member functions belong to one the these three categories: in, out or inout. To make this classification more explicit, the name of the parameter must begin with the prefix 'i' (in), 'o' (out) or 'io' (inout). The first character of the name must be uppercase (ex: iIndex, oElement). See Lifecycle Rules for parameter allocation.
• Use Legal values for each parameter, if this is meaningful and describe the default value, if any
• Use Cyclic reference for each parameter if it is an interface pointer that the constructor keeps as a data member
• Use Lifecycle rules deviation for each each parameter for which the constructor is in deviation with respect to the CNext lifecycle rules for objects, interface pointers, and smart pointers
• If needed, you can add a See also section to create hyperlinks to objects or methods that are related to the global function
• Add a Returns section using the @return tag if the method returns a value
• Use Legal value for the possible returned values
• Add a Throws section using the @exception tag if the method returns a value
• Set hyperlinks to the error classes thrown as exceptions thanks to the @href tag

Don't:

• Forget the period at the end of the class role
• Let types alone in global function signatures. Put dummy arguments instead and use them with @param
• Create hyperlinks to the classes or enums used as types for parameters, since these links are automatically set up

Refer to the following example:

[Top]

Writing Macro and #define Comments

Do:

• Begin with the short role. End it using a period
  • Begin the short role using an action verb, such as Creates, Processes, Adds, Computes, etc.
• Write additional comments, if the short role is not enough, in the Role section
• Build the list of parameters using the @param tag. Don't change the parameter name, since they are used as is in the macro code
• Use Legal values for each parameter, if this is meaningful and describe the default value, if any
• If needed, you can add a See also section to create hyperlinks to objects or methods that are related to the macro

Don't:

• Forget the period at the end of the class role

Refer to the following examples:

[Top]

Writing Collection Comments

Do:

• Write a single comment just after the one that contains the @CAA2Level and @CAA2Usage tags.
  • Write first the @collection tag, followed by the collection class name. If this name is redefined by a typedef, use this redefined name 
  • Go on with the short role. End it using a period
  • Begin the short role using Collection class for pointers to xxx for CATLISTP, or Collection class for xxx for CATLISTV
  • Give, the list of available methods:
    • If all methods are available, for a CATLISTP, write:  All the methods of pointer collection classes are available.
    • If almost all methods are available, some of them being removed using #undef, write: All the methods of pointer collection classes are available, except the following:, and give the list of unavailable methods
    • If few methods are available, write: Only the following methods of pointer collection classes are available:, and give the list of available methods
  • Write at the end: Refer to the articles dealing with collections in the encyclopedia.

Don't:

• Forget the period at the end of the class role

Refer to the following examples:

[Top]

Writing Enumeration Comments

Do:

• Begin with the short role. End it using a period
• Use only a name, or a qualified name, not a sentence.
• Write additional comments, if the short role is not enough, in the Role section
• Build the list of values using the @param tag. Insert a @param tag for each enumerated value
• If needed, you can add a See also section to create hyperlinks to objects or methods that are related to the enum

Don't:

• Forget the period at the end of the short role
• Avoid having enum without identifier, such as
  enum {CATFirstValue, CATSecondValue};
  otherwise, mkman can't refer to it

Refer to the following examples:

[Top]

Writing Operator Comments

Do:

• Begin with the short role. End it using a period
• Depending on the operator, use the standard short roles if there is no overload and if the operator applies to class instances only.

  Operator	Short Role
  Equality operators
  ==	Equality operator.
  !=	Inequality operator.
  Relational operators
  <	Less-than operator.
  <=	Less-than or equal operator.
  >	Greater-than operator.
  >=	Greater-than or equal operator.
  Prefix operators
  ++	Prefix increment operator.
  --	Prefix decrement operator.
  Postfix operators
  []	Subscripting operator.
  .	Member-selection operator.
  ->	Member-selection operator.
  ++	Postfix increment operator.
  --	Postfix decrement operator.
  Unary operators
  +	Unary plus operator.
  -	Arithmetic-negation operator.
  ~	Bitwise-complement (or bitwise-NOT) operator.
  !	Logical-negation (or logical-NOT)  operator.
  *	Indirection (or dereference) operator.
  &	Address-of operator.
  ()	Cast (or type cast, or conversion) operator.
  Additive operators
  +	Addition operator.
  -	Subtraction operator.
  Multiplicative operators
  *	Multiplication operator.
  /	Division operator.
  %	Remainder (or modulus) operator.
  Bitwise operators
  &	Bitwise AND operator.
  ^	Bitwise-exclusive-OR operator.
  |	Bitwise-inclusive-OR operator.
  Bitwise shift operators
  <<	Bitwise left shift operator.
  >>	Bitwise right shift operator.
  Logical operators
  &&	Logical-AND operator.
  ||	Logical-OR operator.
  Assignment operators
  =	Assignment operator.
  *=	Multiplication assignment operator.
  /=	Division assignment operator.
  %=	Remainder (or modulus) assignment operator.
  +=	Addition assignment operator.
  -=	Subtraction assignment operator.
  <<=	Left-shift assignment operator.
  >>=	Right-shift assignment operator.
  &=	Bitwise-AND assignment operator.
  ^=	Bitwise-exclusive-OR assignment operator.
  |=	Bitwise-inclusive-OR assignment operator.
  &=	Bitwise-AND assignment operator.
  Other operators
  ::	Scope resolution operator.
  ?:	Conditional-expression operator.
  ,	Sequential-evaluation (comma) operator.

• If the operator is overloaded, or applies to different objects than the class instances, use an action verb (see example)
• Write additional comments, if the short role is not enough, in the Role section
• If needed, use the @param tag for the parameter
• Use Legal values for the parameter, if this is meaningful
• If needed, use the @return tag.

Don't:

• Forget the period at the end of the short role

Refer to the following examples:

[Top]

Writing Structure Comments

Do:

• Begin with the short role. End it using a period
• Use only a name, or a qualified name, not a sentence.
• Write additional comments, if the short role is not enough, in the Role section
• If needed, add a See also section to create hyperlinks to objects or methods that are related to the struct

Don't:

• Forget the period at the end of the short role

Refer to the following examples:

[Top]

Writing Data Member Comments

Do:

• Begin with the short role. End it using a period
• Use only a name, or a qualified name, not a sentence.
• Write additional comments, if the short role is not enough, in the Role section
• Use Legal values if this is meaningful, and describe the default value set up when instantiating the class or structure, if any

Don't:

• Forget the period at the end of the short role

Refer to the following examples:

[Top]

Writing typedef and constant Comments

Do:

• Begin with the short role. End it using a period
• Use only a name, or a qualified name, not a sentence.
• Write additional comments, if the short role is not enough, in the Role section
• Use the @param tag if the typedef defines:
  • A method prototype, insert a @param tag for each parameter
  • An int or a long used as a field of bits, insert a @param tag for each meaningful bit, usually set using a #define. Do not comment the associated #define. Refer to examples given in Writing Macro Comments
• Add a Returns section using the @return tag if a method prototype is defined with a return value
• If needed, you can add a See also section to create hyperlinks to objects or methods that are related to the typedef of constant

Don't:

• Forget the period at the end of the short role

Refer to the following examples:

[Top]

Tips

These tips can help you in the following areas:

• Correctly writing HRESULT legal values
• Describing methods to scan lists and retrieve items
• Making sure that your weak typed parameters or return values can be used

These tags are:

[Top]

Tips for HRESULT

If your method returns only S_OK and E_FAIL, do not include a Returns section.

Otherwise, if the method can return more than S_OK and E_FAIL, write your list of HRESULT legal values as follows:

...
 * @return
 *   An HRESULT value. 
 *   <br><b>Legal values</b>:
 *   <dl>
 *     <dt>S_OK</dt>
 *     <dd>The component is successfully created
 *         and the interface pointer is successfully returned</dd>
 *     <dt>E_FAIL </dt>
 *     <dd>The component was successfully created,
 *         but the interface query failed</dd>
 *     <dt>E_NOINTERFACE </dt>
 *     <dd>The component was successfully created,
 *         but the it doesn't implement the requested interface</dd>
 *     <dt>E_OUTOFMEMORY </dt>
 *     <dd><dd>The component allocation failed</dd>
 *   </dl>
 */

[Top]

Tips for Lists

You usually provide methods to scan your lists and collections, and to retrieve a given object from the collection. It can be thanks to:

• An iterator with two methods: one to point to the collection first item, such as InitTransitionList below, the other to retrieve the pointed object and move the pointer to the next object, such as GetNextTransition.

  /**
   * Points to the first command transition.
   * @see #GetNextTransition 
   */
  virtual void InitTransitionList();
  
  /**
   * Returns the pointed command transition and points to the next one.
   * <br><b>Precondition</b>: Set the pointer to the first command transition
   * using @href #InitTransitionList before traversing out the command transition
   * list using calls to GetNextTransition enclosed in a loop.
   */
  virtual CATDialogTransition * GetNextTransition();

• A couple of methods: one to get the item count, such as GetElementTypeSize, the other to retrieve the ith item, such as GetElementType.

  /**
   * Returns the count of element types expected by the dialog agent.
   * <br><b>Legal values</b>: 
   * The count of element types ranges from 1 to n.
   */
  int GetElementTypeSize();
  
  /**
   * Returns an element type from those expected by the dialog agent using the element type index.
   * <br><b>Role</b>: This method returns the <tt>iIndex</tt>th element type
   * from those expected by the dialog agent and set using the @href #SetElementType method. 
   * @param iIndex
   *   The index of the element type .
   *   <br><b>Legal values</b>: <tt>iIndex</tt> range starts with 1, which is the default.
   *   Use @href #GetElementTypeSize to get the element type count.
   */
  CATClassId GetElementType(int iIndex = 1);

[Top]

Tips for Weak Typing

Your methods have often weak typed parameters that you didn't want to specialize to ensure future evolutions. For example, a method takes a pointer to CATBaseUnknown as a parameter, but you expect in fact a pointer to a more specific interface. This can also be the case of a return value. The type into which the pointer must be cast to become usable, or the interface to query from the returned one must be described. Nowhere else will the client application programmer get this information.

/**
 * Retrieves the object that does what you want.
 * @param oObject
 *   The retrieved object.
 *   <br><b>Legal values</b>: The object retrieved is an instance of a
 *   a CATSpecObject. Cast the pointer to CATSpecObject to use it.
 */
public HRESULT GetObject(CATBaseUnknown ** oObject);

[Top]

CNext Tag Reference

Some specific tags are used to denote specific entities and generate html tags to present this information consistently. These tags begin with the "at" sign, or @. These tags are:

[Top]

@collection

To identify and provide the name of a collection class. The comment should be inserted at the top of the file, just below the Level and Usage comment, and must be the only comment in the file.

...
// COPYRIGHT DASSAULT SYSTEMES 1999

/**
 * @CAA2Level L1
 * @CAA2Usage U1
 */

/**
 * @collection CATLISTP(CATUnicodeString)
 * Collection class for Unicode strings.
 * ...
 */

[Top]

@deprecated

To denote each entity that should not be used.

/**
 * @deprecated V5R8
 * Removes a file descriptor subscription from a command.
 * This method will be replaced by @href myClass#myMethod
 * The signature of the method has been changed to manage a new functionnality
 * @param iFileDescriptor
 *   The file descriptor.
 * @param iToClient
 *   The command for which the subscription is to be removed.
 * @return 0 if the file descriptor subscription is successfully removed and 0 otherwise.
 * @see #AddFileDescriptor
 */
      int RemoveFileDescriptor(int          iFileDescriptor,
                               CATCommand * iToClient);

The replacing entity, if any, can be specified using the @see or @href syntax, as follows:

/**
 * @deprecated V5R8 IUnknown#QueryInterface
 * ...

[Top]

@description

To create a description section to describe an object.

/**
 * Retrieves a reference to an element of self.
 * @param coordIndex
 *   [in] The index of the desired coordinate (e.g., DNBMath3D::X).
 * @return
 *   A reference to component  of self.
 * @description 
 *   This function returns a reference to component  of self.
 */ 
reference operator[]( CoordinateIndex coordIndex )

[Top]

@exception

To create a Throws section to describe the exceptions thrown by the method

/**
 * Checks that the class to document belongs to JJA's list.
 * ...
 * @exception @href CATSystemError if JJA's laptop is not connected to the network
 */
        HRESULT Check(CATBaseUnknown * pClass);

[Top]

@example

To create an example section.

/**
 * Retrieves a reference to an element of self.
 * @param coordIndex
 *   [in] The index of the desired coordinate (e.g., DNBMath3D::X).
 * @return
 *   A reference to component  of self.
 * @example 
 *   DNBVector3D vector;
 *   vector[ DNBMath3D::X ] = 1.0;
 *   vector[ DNBMath3D::Y ] = 2.0;
 *   vector[ DNBMath3D::Z ] = 3.0;
 *   DNBReal x = vector[ DNBMath3D::X ];
 */ 
reference operator[]( CoordinateIndex coordIndex )

[Top]

@href

To create a hyperlink to other documented entities anywhere in the text.

/**
 * A collection of all the CATCamera instances attached to a document.
 * A camera can be created using the @href CATViewer#NewCamera method.
 * The first seventh cameras of the collection are @href CATCamera3D
 * objects and cannot be modified or removed.
 */
interface CATIACameras : CATIACollection

Do not use tags for monospace fonts (<tt> or <code>) in hyperlinks. See Using Hyperlinks to know which hyperlinks you can use.

[Top]

@nodoc

To denote each entity that you don't want to see in the extracted html file.

/**
 * @nodoc
 */
   CATNotification * GetRadBModifyNotification() const;

/** @nodoc */
    virtual l_CATDialog* GetLetterObject();

/**
  * @nodoc
  * Sets the radio button state.
  * @param iState
  *   The radio button state.
  *   <b>Legal values</b>: It can be set to either
  *   <tt>CATDlgCheck</tt> to check the radio button or to
  *   <tt>CATDlgUncheck&lgt;/tt> to uncheck it.
  * @param iNotify
  *   Requests that a notification be sent when the state is set.
  *   This notification is an instance of the CATDlgRadBModifyNotification
  *   class.
  *   <b>Legal values</b>: 0 to send the notification, and 1, or a non null
  *   value, to prevent from sending it. 1 is the default.
  */
     void SetState(CATULong iState, int iNotify=1);

[Top]

@param

To denote each method or global function parameter.

/**
 * Constructs a radio button.
 * @param iParent
 *   The radio button command and containment parent. 
 * @param iObjectName
 *   The radio button identifier.
 *   This identifier is used to assign resources to the radio button,
 *   namely its title displayed beside it.
 * @param iStyle
 *   The radio button style. 
 *   <br><b>Legal values</b>: The default style expressed by the
 *   NULL default value sets the radio button title to the right
 *   of the radio button.
 *   This is the only available style
 */
        CATDlgRadioButton(CATDialog       * iParent,
                          const CATString & iObjectName,
                          CATDlgStyle       iStyle=NULL);

[Top]

@return

To create a Returns section to describe the returned value of a method.

/**
 * Analyzes a notification received.
 * ...
 * @return
 *   The notification propagation mode.
 *   <br><b>Legal values</b>: <tt>CATNotifTransmitToFather</tt> (=0)
 *   if the notification should go on along the command tree structure, or
 *   <tt>CATNotifDontTransmitToFather</tt> (=1) if it should stop.
 */
  virtual CATNotifPropagationMode AnalyseNotification(CATCommand      * iFromClient,
                                                      CATNotification * iNotification);

If the returned value can take all the values of the enum, the hyperlink set by mkman to the enum documentation can be enough. Nevertheless, if a only subset of these values can be returned, or if the meaning of is context-dependent, you must use the Legal values named field.

If the method returns a HRESULT, you can find examples in global functions.

[Top]

@see

To create a See also section that contains hyperlinks to other documented entities, usually located at the end of the role of a class or method. Use the comma to separate two successive entity.

/**
 * Base class for all collaborating objects.
 * <tt>CATCommand</tt> is the base class for all objects that need to collaborate by
 * means of
 * <ul>
 * <li>The send/receive communication protocol</li>
 * <li>The callback mechanism.</li>
 * </ul>
 * <p><tt>CATCommand</tt> supplies the methods to convey notifications and their
 * associated data to the object either able to process user's requests in response
 * to user interactions, or that has set callbacks on to user activable objects.
 * @see CATCallbackManager, CATNotification
 */
 class ExportedByJS0FM CATCommand : public CATEventSubscriber 

Another example about an enumeration to refer to methods that are members of the same class that the enum.

/**
 * Subscribing type, used as parameter of the methods <tt>Subscribe</tt> and
 * <tt>RemoveSubscribe</tt>. 
 * @param CATSubscribeEndTransaction
 *   The subscribing command must be called when the transaction is completed
 * @param CATSubscribeIdle
 *   The call must be performed when the process enters the main event loop
 * @see #Subscribe, #RemoveSubscribe
 */
 enum
 {
   CATSubscribeEndTransaction=1,
   CATSubscribeIdle =2
 };

See Using Hyperlinks to know which hyperlinks you can use.

[Top]

@SOM and @EOM

@SOM (Start Of Macro) and @EOM (End Of Macro) delimit a macro usage in a C++ header. mkman does not replace the macro by its contents like the preprocessor. It simply identifies the enclosed statement as a macro and thus does not attempt to parse it, and copies the macro in the output html file as it is in the header file.

Header file:

void  normalize()  /**@SOM*/ DNB_THROW_SPEC((DNBEZeroVector)) /**@EOM*/  ;

HTML File:

o normalize

public void normalize

(

)

DNB_THROW_SPEC((DNBEZeroVector))

[Top]

Named Field Reference

Some comments may appear repeatitively, such as the parameter legal values, or the deviation to the lifecycle management. Use name fields to describe them. Available name fields are:

[Top]

Lifecycle Rules

Memory Management for Non-scalar types (Except Interfaces)

When calling member functions, parameters with non scalar types (structures, character strings, classes) memory must be allocated and deallocated according to strict rules in order to avoid memory leaks or untimely memory release.

• in parameters must be allocated by the caller before calling the member function and freed by the caller after the function has returned
• out parameters must be allocated by the callee within the body of the member function. The caller is responsible for freeing the allocated memory after the function has returned.
• inout parameters must be allocated by the caller before calling the member function. The callee can optionally replace the sent value by a value of its own: it deallocates the value sent by the caller and allocates a new value. The caller is responsible for freeing returned values after the function has returned.

There are two memory allocation mechanisms in C++:

1. Heap allocation. It is done using the C++ new and delete operators. This mechanism can be used for all three kinds of parameters (in, out, inout). If you use other means, such as malloc and free, you must describe them
2. Stack allocation (auto variables). This mechanism can be only be used if the variable is allocated and deallocated in the same scope. Thus, it can only be used for in parameters.

[Top]

Reference Counting for Interfaces

Parameters of type interface must use the rules defined by COM for memory management. COM defines two functions IUnknown::AddRef() and IUnknown::Release() to perform reference counting (see <10> for examples).

AddRef must be called on interface pointers in the following situations:

• When writing a non-null interface pointer to a local variable.
• When a callee writes a non-null interface pointer to an out or inout parameter of a member function.
• When a callee returns a non-null interface pointer as the physical result of a function.
• When writing a non-null interface pointer to a data member of an object.

Release must be called on interface pointers in the following situations:

• Prior to overwriting a non-null local variable or data member.
• Prior to leaving the scope of a non-null local variable.
• When a callee overwrites an inout parameter whose initial value is non-null. Note that out parameters are assumed to be null on input and must never be released by the callee.
• Prior to leaving the destructor of an object that has a non-null interface pointer as a data member.

Note that in the case of in parameters, it is not necessary to call AddRef before calling the member function and Release upon return of the member function.

[Top]

html Tag Reference

You can use html tags in your comments, except tags, such as <H1>, <H2>, as any other structuring tags. Main html tags you can use are:

[Top]

Setting Hyperlinks

Hyperlink anchors are automatically generated on the following entities:

• For any documented class or interface, global enum, or global function, mkman creates an html file. This file can be used as a target for any hyperlink sets in any class or interface of the same framework, or of any prerequiring framework. Example: mkman generates CATBaseUnknown.htm from CATBaseUnknown.h, which can be used as a target in an hyperlink created using @see or @href, such as in:

  ... @href CATBaseUnknown ...
  ...
  @see CATBaseUnknown

  Note that the htm suffix must not be used.

• For each method or set of overloaded methods, a simple anchor is created with just the method name for the first method occurrence in the class, that you can use as a target of an hyperlink set in any class or interface of the same framework, or of any prerequiring framework.

  Use @href CATCommand#CATCommand to instantiate commands.

  that sets the same hyperlinks as:

  <a href="../System/CATCommand.htm#CATCommand">CATCommand::CATCommand</a>

  which reads in the html file as follows:

  Use CATCommand::CATCommand to instantiate commands.

  This hyperlink leads to the beginning of the section where the first overloaded method is found.

  Preferably, use this hyperlink in place of the following if you don't need to refer to a specific method among the set of overloaded methods.

• For any entity documented in a class or an interface, mkman generates an anchor used in the index and that you can use as a target of an hyperlink set in any class or interface of the same framework, or of any prerequiring framework. Example: mkman generates the anchor:

  CATCommand(CATCommand*,CATString*const)

  for the CATCommand constructor:

  CATCommand(CATCommand * iEventManager,
             CATString  * const iName);

  Leading and trailing blanks are removed, as well as blanks and dummy arguments in signatures. You can refer to such a method as follows:

  ... @href CATCommand#CATCommand(CATCommand*,CATString*const) ...

  that sets the hyperlink as:

  <a href="../System/CATCommand.htm#CATCommand(CATCommand * iEventManager, CATString * const iName)">CATCommand.CATCommand</a>

  This hyperlink directly leads to the appropriate method.

  Preferably, don't use this hyperlink. Use the preceding hyperlink instead if you don't need to refer to a specific method among the set of overloaded methods.

Hyperlink syntax:

• @see CATBaseUnknown or @href CATBaseUnknown sets an hyperlink to the class CATBaseUnknown. It can only be used from any entity that IS NOT a CATBaseUnknown member
• @see CATBaseUnknown#AddRef or @href CATBaseUnknown#AddRef sets an hyperlink to the CATBaseUnknown::AddRef method. It can only be used from any entity that IS NOT a CATBaseUnknown member
• @see #AddRef or @href #AddRef sets an hyperlink to the AddRef method.  It can only be used from any entity that IS a CATBaseUnknown member.

[Top]

[Top]

History

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