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.
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.
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:
@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 foobecause it doesn't include any explanatory text. The line should include explanatory text:
* @param foo holds the latest Bar instance
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.
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 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
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.