JMRI: Use of Javadoc and UML
Author: Bob Jacobsen
Keywords: JMRI technical code UML Javadoc

# 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 Oracle 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 Java packages 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. If you don't have any annotations you want to include, please include

`@edu.umd.cs.findbugs.annotations.DefaultAnnotation(value={})`

which helps some of our build systems minimize recompilation. (For more on that annotation, see here)

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` instead, see above.

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 &gt;, &amp; and &lt; (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"
  Probable 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 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 `@Override` 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.

CI may fail if invalid JavaDoc is uploaded.

## 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, ie this UML Class Diagram Tutorial. 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 class diagram embedded in Sensor interface Javadoc. For a more complex example see the class diagram in the ProgModeSelector class Javadoc.

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 its 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 website. This is done automatically by the CI system, so you generally don't have to deal with it.