How to Write Component Comments

August 29, 2003

This document describes the format that we use to write the component comments in J-Sim. The users are encouraged to follow the format if they wish to incorporate their components in J-Sim in future releases.

1 Javadoc

We follow the convention adopted in writing comments for Javadoc. In particular, the comments written for a class, its field variables or its field methods should start with "/**" and end with "*/". The format embraced within "/**" and "*/" basically follows the HTML syntax. A sample of class comments is given below:

/**
 * A pseudo object for illustrating how to write comments that are well-suited 
 * for <a href="http://java.sun.com/products/jdk/javadoc/writingdoccomments/index.html">Javadoc</a>
 * to generate class reference.
 * Java keywords, package names, class names, method names, interface names,
 * field names, argument names and code examples are offset by &ltcode&gt...&lt/code&gt.
 * For example, <code>java.util.Vector</code> is a class name. 
 *
 * @author John Doe
 * @version 1.0, 10/17/2000
 * @see java.util.Vector
 */

The result generated by Javadoc is shown below:

public class PseudoObject
extends java.lang.Object

A pseudo object for illustrating how to write comments that are well-suited for Javadoc to generate class reference. Java keywords, package names, class names, method names, interface names, field names, argument names and code examples are offset by <code>...</code>. For example, java.util.Vector is a class name.

Version:
1.0, 10/17/2000
Author:
John Doe
See Also:
Vector

2 Component Comments

A component is completely specified by it contracts, events, behavior and properties.

Contracts are usually described in separate classes that extend drcl.comp.Contract. Events are encapsulated in the event message class defined in drcl.comp.contract.EventMsg. Basically, it has the following fields:

In a component document, we are particularly concerned with the type and the object fields.

The behavior (or component contract) of a component describes how inputs may affect the states of the component and/or may generate certain outputs at certain ports. The behavior may be trivial (and therefore be omitted) if the bound port contracts have fully described the component's behavior.

The properties of a component follows the pattern defined in the JavaBeans specification. Basically, a property x is discovered if the "setter" method void setx(<type>) and the "getter" method <type> getx(), can be found in the class. One can override this low-level class introspection by explicitly providing a java.beans.BeanInfo class for the class. For example, the properties of drcl.comp.Component are explicitly defined in drcl.comp.ComponentBeanInfo.

We use the following example to illustrate how component comments are written. The following example does not describe the component behavior because the bound contracts (IDLookup and IDConfig) completely specify the component:

/**
 * The component that manages the identities of the network node.
 * 
 * <p>Contracts:
 * <ul>
 * <li> <code>.idlookup@server</code>: {@link drcl.inet.contract.IDLookup IDLookup}.
 * <li> <code>.idconfig@server</code>: {@link drcl.inet.contract.IDConfig IDConfig}.
 * </ul>
 * 
 * <p>Events:
 * <ul>
 * <li> <code>.id@event</code>: Type "Identity Added", Object is the identity being added in
 *		<code>drcl.data.LongObj</code>.
 * <li> <code>.id@event</code>: Type "Identity Removed", Object is the identity being removed in
 *		<code>drcl.data.LongObj</code>.
 * </ul>
 * 
 * <p>Properties:
 * <ul>
 * <li> <code>defaultID</code>: the default identity of the node.
 * <li> <code>IDs</code>: array of the static identities (won't be timed out) of the node.
 * </ul>
 * 
 * @author Hung-ying Tyan
 * @version 1.0, 10/17/2000
 * @see drcl.inet.contract.IDLookup
 * @see drcl.inet.contract.IDConfig
 * @see drcl.inet.CoreServiceLayer#EVENT_ID_CHANGED_PORT_ID
 * @see drcl.inet.CoreServiceLayer#EVENT_IDENTITY_ADDED
 * @see drcl.inet.CoreServiceLayer#EVENT_IDENTITY_REMOVED
 */

The result generated by Javadoc is shown below (the following links are established relative to the javadoc root directory and are hence broken here):

public class Identity
extends Module

The component that manages the identities of the network node.

Contracts:

Events:

Properties:

Version:
1.0, 10/17/2000
Author:
Hung-ying Tyan
See Also:
IDLookup, IDConfig, CoreServiceLayer.EVENT_ID_CHANGED_PORT_ID, CoreServiceLayer.EVENT_IDENTITY_ADDED, CoreServiceLayer.EVENT_IDENTITY_REMOVED, Serialized Form

* JAVA and all JAVA-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

~ END ~