JMRI Code: 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.

It's recommended that any significant Java package contain a package-info.java file to contain any needed package-level documentation. (It can also contain any annotations you want to apply to all classes in the package) Previously, we used package.html files for this. 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.

HTML in Javadoc

The Java 8 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. In addition, Java 11 will eventually require us to write HTML 5 Javadoc content; keeping it orderly now will help with that migration later.

We run the ant scanhelp job during integration to keep errors from accumulating; you can run that on your own changes to the code to get feedback early.

The rest of this section is hints and tips on HTML 4.01.

You have to properly escape the >, & and < characters, e.g. to show a generic type. To do that, either escape them individually by writing >, & and < (note the trailing semi-colon) or place the entire bit of text in {@literal ...} or {@code ...} blocks.

Some error messages that can result from this 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 ">" or wrap it with @literal as in

        {@literal 0.0 -> 1.0.}

and

        opcodes {@code <opc, string description>} via

Definitely use @code{...} in Javadoc comments instead of trying to provide HTML-style elements like <tt> and <code>, as they won't format correctly.

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.

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

Inheriting Javadoc comments

When you write a method that overrides a method (or signature) in a superclass, you should always use the @Overrides annotation to indicate that:

  @Override
  public void methodName() {
    // doing something
  }

If the method is similar enough to the superclass method, you can just "inherit" the Javadoc from the superclass:

  /**
   * {@inheritDoc}
   */
  @Override
  public void methodName() {
    // doing something
  }

(If there's no Javadoc in the superclass, consider adding your comments there instead of on your new method and inheriting them; that kills two birds with one stone!)

You can add or replace some of the documentation, e.g.

  /**
   * {@inheritDoc}
   * 
   * This implementation uses the ReallyMarvelous algorithm for improved speed.
   */
  @Override
  public void methodName() {
    // doing something
  }

General comments add to the documentation from the superclass; @param and @return tags replace the documentation from the superclass.

Reducing the Number of Missing Comments

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 2300 (as of 2017-10-01, down from 3975 on 2017-02-20; progress!). 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.