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 <code>...</code>.
* 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:
- Time (
double): when the event occurs. - Port (
drcl.comp.Port): where the event
message is exported. - Type (
String): type of the event. - Object (
Object): the objects regarding the
event. - Description (
String): description of the
event.
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:
.id@event: Type "Identity Added",
Object is the identity being added in drcl.data.LongObj.
.id@event: Type "Identity Removed",
Object is the identity being removed in drcl.data.LongObj.
Properties:
defaultID: the default identity of the node.
IDs: array of the static identities (won't
be timed out) of the node.
- 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 ~
|