Adding IDL documentation comments

EAServer Manager creates HTML documentation files for each IDL module in the html/ir subdirectory.

At a minimum, the HTML file lists the datatypes and interfaces defined in the module. You can embed additional documentation text for a datatype, interface, or method in a C-style comment placed immediately above the declaration. EAServer ignores C++-style line-end comments when generating HTML documentation. That is, text within comments that use double slashes, //, to delineate the comment text is ignored.

Within the C-style comment, add text describing the item to the comment, as in the example below. If desired, you can use HTML codes to format the text. But do not use heading tags such as <H1>, <H2>, and so forth, because they conflict with tags that are already used to structure the sections of the generated output.

The IDL fragment below contains an example of a documentation comment:

/**
 ** Example method to demonstrate user-defined
 ** exceptions.
 ** <P>Pass <I>yes_no</I> as <code>true</code> 
 ** if you want an exception thrown.
 ** <P>Returns input value of <I>yes_no</I>
 ** parameter.
 */
boolean throwException 
(
in boolean yes_no
)
raises 
(
myException
);

You need not use the spacing conventions illustrated in this example. EAServer Manager treats any C-style comment as an IDL documentation comment. However, when you save in the IDL Editor window, EAServer Manager reformats all C-style comments to match this example’s spacing convention.