CAA V5 Automation Documentation Rules

Rules and Standards	CAA V5 Automation Documentation Rules Hints and tips to tag and write comments in your IDL files
Technical article

Abstract

This article gives you information on how you can document your IDL interface header files using specific comments that are processed to build html files.

What Do You Need to Document?
How Do You Document?
A Simple Sample
Writing Comments
mkdcidl Tag Reference
Named Field Reference
html Tag Reference
Setting Hyperlinks
Creating the html Files

What Do You Need to Document?

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

IDL Interface
IDL Method (Function and Subroutine)
IDL Property
IDL Collection
IDL Enumeration

This applies to L1 entities that are located in the PublicInterfaces directories of the exposed frameworks.

[Top]

How Do You Document?

Interfaces and all the stuff they include, are documented thanks to information enclosed into specific comments inserted in the idl files. The idl statements and the comments are then processed to produce an organized set of html files in which you and the users of your interfaces 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 interface, method, etc., it is intended to describe.

/**
 * Represents the document.
 * The document is the object handled by the operating system as a whole
 * that stores your data in files and databases.
 * It is assigned a type determined by its contents. It may contain other
 * documents with a different type. For example,
 * a PartDocument contains a part and can be contained in a ProductDocument.
 * A workshop is associated with a document to gather all the commands
 * that can be used to create, modify, and edit the objects making up the
 * the document. These commands are arranged in menus and toolbars.
 * @see CATIAPartDocument, CATIAProductDocument, CATIADrawingDocument
 */
interface CATIADocument : CATIABase
...

[Top]

A Simple Sample

[Top]

Writing Comments

You will find below some tips to write comments for interfaces, methods, properties, collections, and enumerations.

[Top]

Writing IDL Interface Comments

Do:

Begin with the short role. End it using a period
- Write short roles for IDL interfaces: "Represents the xxx object"
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. You can also, and better, write this role in a technical article in dedicated to the object represented by this interface and in which a small object diagram centered on this object can be inserted
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
Create hyperlinks to the base interfaces, since the inheritance tree is automatically built with such hyperlinks

IDL File	html File
CATIAApplication.idl	Application.htm

[Top]

Writing IDL 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.
- If the method returns a value using the IDLRETVAL keyword, use Returns
- If the method retrieves a value, or an array, in an output parameter that doesn't use the IDLRETVAL keyword, use Retrieves
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. Do not include the parameter returned using the IDLRETVAL keyword
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 An object of the collection.
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 function or subroutine
Add a Returns section using the @return tag if the method returns a value, except for a getter for which it is obvious
Use Legal values to describe each possible returned value
Create an Example section that illustrates the method common usage. Write first a short description of the example before the code in which you highlight the function or subroutine name in red.

Don't:

Forget the period at the end of the short role
Create hyperlinks to the classes or enums used as types for parameters, since these links are automatically set up

IDL File	html File
Sub.idl	Sub.htm	Shows a Sub
Func.idl	Func.htm	Shows a Func

[Top]

Writing IDL Property Comments

Do:

Begin with the short role. End it using a period
The short role must begins with Returns for a read-only property, and with Returns or sets for a read-write property.
Write additional comments, if the short role is not enough, in the Role section
Create an Example section that illustrates the property common usage. Write first a short description of the example before the code in which you highlight the property name in red.

Don't:

Forget the period at the end of the short role

Refer to the following examples:

IDL File	html File
ActiveViewer.idl	ActiveViewer.htm	Read only property
WindowState.idl	WindowState.htm	Read/write property

[Top]

Writing IDL Collection Comments

Do:

Begin with the short role. End it using a period.
The short role must begin with A collection of
Write additional comments, if the short role is not enough, in the Role section
If needed, you can add a See also section to create hyperlinks to objects or methods that are related to the collection

Don't:

Forget the period at the end of the class role

Refer to the following examples:

IDL File	html File
CATIACameras.idl	Cameras.htm	Collection with Item and Remove methods
CATIALightSources.idl	LightSources.htm	Collection with Add, Item, and Remove methods

[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

Refer to the following example:

IDL File	html File
CatNavigationStyle.idl	CatNavigationStyle.htm

[Top]

mkdcidl 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:

Tag	Definition
@nodoc	To denote each entity that you don't want to see in the extracted html file
@param	To denote each method or global function parameter, enum value, struct member, and possibly typedef value
@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
@href	To create a hyperlink to other documented entities anywhere in the text
@return	To create a Returns section to describe the returned value of a method

[Top]

@nodoc

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

/**
 * @nodoc
 */
#pragma PROPERTY Windows
    HRESULT get_Windows(out /*IDLRETVAL*/ CATIAWindows oWindows);
    
/** @nodoc */
#pragma PROPERTY Windows
    HRESULT get_Windows(out /*IDLRETVAL*/ CATIAWindows oWindows);

/**
 * @nodoc
 * Returns the collection of windows currently managed by the application.
 * <dl>
 * <dt><b>Example:</b>
 * <dd>
 * This example retrieves in <tt>WinCollection</tt> the collection of
 * windows currently managed by the <tt>CATIA</tt> application.
 * <pre>
 * Dim WinCollection As Windows
 * Set WinCollection = CATIA.<font color="red">Windows</font>
 * </pre>
 * </dl>
 */
#pragma PROPERTY Windows
    HRESULT get_Windows(out /*IDLRETVAL*/ CATIAWindows oWindows);

[Top]

@param

To denote each sub or func parameter, except the parameter returned as an IDLRETVAL.

/**
 * Sets the origin point which the hole is anchored to.<br> 
 * If mandatory, the entry point will be projected onto a tangent plane.
 * @param iX
 *   Origin point x absolute coordinate
 * @param iY
 *   Origin point y absolute coordinate
 * @param iZ
 *   Origin point z absolute coordinate
 * <dl>
 * <dt><b>Example:</b>
 * <dd>The following example sets the coordinates of
 * hole <tt>firstHole</tt> to 10., 20., -5. :
 * <pre>
 * firstHole.<font color="red">SetOrigin</font> 10., 20., 5.
 *</pre>
 * </dl>
 */
 HRESULT	SetOrigin ( in double iX,
                     in double iY,
                     in double iZ );

[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.

/**
 * Represents the document.
 * The document is the object handled by the operating system as a whole
 * that stores your data in files and databases.
 * It is assigned a type determined by its contents. It may contain other
 * documents with a different type. For example,
 * a PartDocument contains a part and can be contained in a ProductDocument.
 * A workshop is associated with a document to gather all the commands
 * that can be used to create, modify, and edit the objects making up the
 * the document. These commands are arranged in menus and toolbars.
 * @see CATIAPartDocument, CATIAProductDocument, CATIADrawingDocument
 */
interface CATIADocument : CATIABase

You can also refer to a method or property using @see.

/**
 * ...
 * @see CATIADocuments#Add, CATIADocuments#Item
 */
 interface CATIADocument : CATIABase

See Using Hyperlinks to know which hyperlinks you can use.

[Top]

@href

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

/**
 * Represents the camera.
 * The camera is the object that stores a viewpoint saved from a viewer
 * at a given moment using the @href CATIAViewer#NewCamera method of
 * the @href CATIAViewer object.
 * The viewpoint stored in the camera can then be applied to another viewer
 * to display the document in this viewer according to this viewpoint.
 */
 interface CATIACamera : CATIABase

Do not use @href in the short role of any entity. Do not use tags for monospace fonts (<tt> or <code>) in hyperlinks. See Using Hyperlinks to know which hyperlinks you can use.

[Top]

@return

To create a Returns section to describe the value returned by a Func using IDLRETVAL.

/**
 * Returns a document using its index or its name from the documents
 * collection. 
 * ...
 * @return
 *   The retrieved document
 * ...
 */
 HRESULT Item(in CATVariant iIndex, out /*IDLRETVAL*/ CATIADocument oDocument);

Use the Legal values named field whenever possible. If the returned value can take all the values of an enum, the hyperlink set by mkdcidl 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.

[Top]

Named Field Reference

Some comments may appear repeatitively, such as the parameter legal values. Use named fields to describe them. Available named fields are:

Named Field html Tags	Definition
`<b>Role</b>:`	To describe the role of a class, an interface, a global function, an enum, a macro, a typedef
`<br><b>Role</b>:`	To describe the role of a method or data member
`<br><b>Precondition</b>:`	To describe the valid system context or state required before calling the method. Applies to methods
`<br><b>Postcondition</b>:`	To describe the system context or state that the method leaves or should leave when returning. Applies to methods
`<br><b>Legal values</b>:`	To describes parameter range of valid values, including the default value. Applies to method parameters

[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:

Tag	Definition
`<br>`	To insert a line break
`<p>`	To create a new paragraph
`<b>`bold`</b>`	To enclose a text that should be rendered in boldface: bold
`<i>`italic`</i>`	To enclose a text that should be rendered in italic font: italic
`<tt>monospace</tt>`	To enclose a text that should be rendered in `monospace` font. You can also use `<code>` and `</code>`. Use these tags to enclose class names, method names, enum values, etc. that you don't use as hyperlinks, that is that do not follow a <a href="#see">see<a> or a <a href="#href">href<a> tag
`<pre>` and `</pre>`	To enclose lines that should be rendered with existing line breaks and using monospace font. It forces a line break
`<ul>` and `</ul>`	To specify that the following block of text is a bulleted (or unordered) list. Each item begins with a `<li>`
`<ol>` and `</ol>`	To specify that the following block of text is an ordered list. Each item begins with a `<li>`
`<dl>` and `</dl>`	To specify that the following block of text is a definition list. Each defined term is denoted with `<dt>`, and each associated definition is denoted using `<dd>`

[Top]

Setting Hyperlinks

Hyperlink anchors are automatically generated on the following entities:

For any documented interface or enum mkdcidl 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: mkdcidl generates Application.htm from CATIAApplication.idl, which can be used as a target in an hyperlink created using @see or @href, such as in:
```
... @href CATIAApplication ...
...
@see CATIAApplication 
```
Note that the htm suffix must not be used.
For each method or property, a simple anchor is created with just the method or property name, 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 CATIAApplication#Documents to retrieve the document collection associated with the application.
```
that sets the same hyperlinks as:
```
<a href="../InfInterfaces/CATIAApplication.htm#Documents">CATIAApplication.Documents</a>
```
which reads in the html file as follows:

Use CATIAApplication.Documents to retrieve the document collection associated with the application.

Hyperlink syntax:

@see CATIAApplication or @href CATIAApplication sets an hyperlink to the interface CATIAApplication. It can only be used from any entity that IS NOT a CATIAApplication member
@see CATIAApplication#Documents or @href CATApplication#Documents sets an hyperlink to the CATIAApplication.Documents property. It can only be used from any entity that IS NOT a CATIAApplication member
@see #Documents or @href #Documents sets an hyperlink to the Documents property. It can only be used from any entity that IS a CATIAApplication member.

[Top]

Creating the html Files

Run mkdcidl for the IDL interfaces and enum of your framework. If you have interfaces in ProtectedInterfaces, run mkdcidl -protected

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

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

interfaces contains:

A directory and a file per framework:
- The directory contains a html file for each existing IDL file, that contains the documentation extracted from the IDL file and that has the same name than the interface or enum file, but is suffixed with htm. For example, the InfInterfaces directory is for the InfInterfaces framework
- A file per framework that contains the framework interface and enum lists. For example, the InfInterfaces.htm file is for the InfInterfaces framework
Three files:
- AllNames.htm contains an index of all the interfaces, properties, methods, and enums
- main.htm contains the list of frameworks
- tree.htm contains the interfaces arranged using their inheritance tree structure

You cannot run mkdcidl for a single interface or framework. It applies to the whole workspace, but it's fast.

[Top]

Rules and Standards