Re: Javadoc resources for tech writers?
I'm editing Javadoc that was written by offshore developers. I don't know
Java, so I'm already at a loss, and the translation errors just add to the
confusion.
As far as I remember, Javadoc is not written, rather it is generated in much the same way as a toc in Word or Frame. It picks up some or all of the following:
-managed object name (A managed object is any resource in an open network that is managed by the network. It is defined by its attributes, the actions that can be performed on it, its behaviour as a result of the actions, and the reports (notifications) it returns.)
-parent class (The class from which this object derives)
-distinguished name (DName)(A DName identifies the position of the object, through all levels of the hierarchy, in a management information tree or domain name system.)
-attributes (An attribute is a property of a managed object, indicating through its type (integer, string, etc.) and its value the characteristics, state, and behaviour of the object)
-associations (Any relationship or dependency between two or more objects)
-actions (An operation that can be performed on or by a managed object. All objects in the same class share the same actions.)
-exceptions (Errors associated with the object)
Here's a suggested layout for your cleaned-up javadoc:
H1: Object_Name
para: description of the object (purpose, etc)
H2: Parent class
para: name of parent class, plus x-ref to page on which it is described.
H2: DName
para: DName form; params list if required
H2: Attributes
table: attribute name | description | whether the object is read-write or read-only | whether the attribute MUST be or MAY be defined (mandatory or optional) | possible values
H2: Associations
para: list of related objects
H2: Actions
table: actionName | description | params | returns
H2: Exceptions
table: exception string | cause of the error | command or request that caused it | object(s) it is associated with | node or application it is associated with.
If exceptions are numerous, you might want to provide them in a separate chapter.
HTH
~~~~~~~~~~~~~~~~~~~~~
Lyndsey Amott
www.docsymmetry.com
Winnipeg, MB R3G 2J3
Follow-Ups:
- Re: Javadoc resources for tech writers?, Guy K. Haas
References:
Javadoc resources for tech writers?: From: Joyce Fetterman
Previous by Author:
Re: MS Word--Formatting text in cross reference fields
Next by Author:
Re: Javadoc resources for tech writers?
Previous by Thread:
Javadoc resources for tech writers?
Next by Thread:
Re: Javadoc resources for tech writers?
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads