Software documentation

Development tools

Structure

Techniques and Standards

How To

Functional Info

Background Info

JMRI: Use of Javadoc and UML

The 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 Developers

The 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 documentation. It's now recommended that any significant Java package contain a package-info.java 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 package.html files, but new packages should include a package-info.java copied from java/package-info.java.

A nice discussion of how to use the "deprecated" label in documentation is available on the "How and When To Deprecate APIs" page.

The Javadoc content is interpreted as HTML 4.01, so it should be valid HTML 4.01. If it's not, it probably won't display properly when somebody wants to understand your code, so it's in your interest to get the Javadoc comments right.

For example, you have to properly handle & and < character, e.g. to show a generic type. To do that, place the test in {@literal ...} or {@code ...} blocks.

You also have to (sometimes) end your paragraph tags to start another type of element, e.g. lists:


 * Some text that forms a paragraph
 * <p>
 * Some more text. 
 * <p>
 * Last text, start list. Note end-paragraph tag.
 * </p><ul>
 *    <li>List item
 * </ul>

Note that HTML 4.01 wants paragraph tags to be ended with </p>, and that you can't have a list inside a paragraph.

Some error messages and their translations:

"malformed HTML"
"bad HTML entity"
Probably use of &, < or > characters on the indicated line
"bad use of '>'"
Probably using '>' as a character, e.g. A -> B. If so, replace with "&gt;" or wrap the line with @literal
Finally, note that this Javadoc line is malformed:

 * @param foo

because it doesn't include any explanatory text. The line should include explanatory text:

 * @param foo holds the latest Bar instance

.

We are currently suppressing the "missing" class of warnings, which warns of missing @param or @return tags. Note that Javadoc will throw an error if the number of "missing" warnings exceeds 3975 (as of 2017-02-20). Once the number of these warnings is reduced to a managable level, we will stop suppressing them.

For a summary of current Javadoc errors in the code, see Builds Jenkins job.

UML and UmlGraph for Developers

UML 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.

Our Ant Javadoc processing makes basic UML class diagrams automatically. For an example, see the Sensor interface Javadoc, then click the "Show UML Class Diagram link" to see the class diagram embedded in it. For a more complex example see ProgModeSelector class Javadoc then click the "Show UML Class Diagram link" to see the class diagram embedded in it.

You can also define custom UML diagrams using PlantUML. For an example of the source syntax to define state and sequence diagrams, see the java/src/jmri/jmrix/lenz/XNetProgrammer.java file. The resulting diagrams are visible in the Javadoc output.

PlantUml can also be used for standalone diagrams, c.f. the connection sequence diagram. To do this, create a .txt file, and then manually process with

      java -jar lib/plantuml.jar help/en/my/file/path/name
      
A .png with the diagram will be created alongside the source.

Processing

The standard JMRI Ant build provides three documentation targets:
javadoc
Create the text Javadocs in the local doc/ directory. Open doc/index.html for access.
javadoc-uml
Create the UML diagrams and Javadocs in the local doc/ directory. Open doc/index.html for access.
uploadjavadoc
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.

Manual Diagrams