JMRI: Use of JavaDoc and UMLThe JMRI library provides the majority of its API documentation via JavaDoc and UML.
We also use Java annotations to document our code structure.
We use the UmlGraph doclet to automatically create the UML diagrams in our JavaDoc pages.
JavaDoc for DevelopersThe JavaDoc tutorial is a good, but somewhat long, introduction to JavaDoc. A brief summary of the formatting and tags can be found in the reference.
Traditionally, the Java packages in JMRI have used
package.html files to contain any needed package-level
It's now recommended
that any significant Java package contain a
file for this.
Only a few of these have been included in JMRI so far, and
it's not a high priority to replace existing
but new packages should include a
A nice discussion of how to use the "deprecated" label in documentation is available on the "How and When To Deprecate APIs" page.
UML and UmlGraph for DevelopersUML is a broad and deep language for describing the structure, design and behavior of computing systems. JMRI primarly uses UML class diagrams for documenting its structure. Many UML tutorials are available on the web. In particular, a good starting point is the Object Mentor introduction to class diagrams. For more detail, please see Atlas UML course or Embarcadero Software introduction.
ProcessingThe standard JMRI Ant build provides three documentation targets:
- Create the text JavaDocs in the local doc/ directory. Open doc/index.html for access.
- Create the UML diagrams and JavaDocs in the local doc/ directory. Open doc/index.html for access.
- Upload the current documentation in the local doc/ directory to the jmri.org web site. This is done automatically by the CI system, so you generally don't have to deal with it.