Serge NOEL
246 lines
10 KiB
Plaintext
246 lines
10 KiB
Plaintext
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy for HTML5 for Apple macOS version 5.8.0">
|
|
<title>JMRI: Use of Javadoc and UML</title>
|
|
<meta name="author" content="Bob Jacobsen">
|
|
<meta name="keywords" content="JMRI technical code UML Javadoc">
|
|
<!--#include virtual="/help/en/parts/Style.shtml" -->
|
|
</head>
|
|
<body>
|
|
<!--#include virtual="/help/en/parts/Header.shtml" -->
|
|
|
|
<div id="mBody">
|
|
<!--#include virtual="Sidebar.shtml" -->
|
|
|
|
<div id="mainContent">
|
|
<h1>JMRI Code: Use of Javadoc and UML</h1>
|
|
|
|
<p>The JMRI library provides the majority of its API documentation via <a href=
|
|
"https://www.oracle.com/java/technologies/javase/javadoc.html">Javadoc</a> and <a href=
|
|
"https://en.wikipedia.org/wiki/Unified_Modeling_Language">UML</a>.</p>
|
|
|
|
<p>We also use Java <a href=
|
|
"https://docs.oracle.com/javase/tutorial/java/annotations/index.html">annotations</a> to
|
|
document our code structure.</p>
|
|
|
|
<p>We use the <a href="https://github.com/dspinellis/UMLGraph">UmlGraph</a> doclet to automatically create
|
|
the UML diagrams in our Javadoc pages.</p>
|
|
|
|
<h2>Javadoc for Developers</h2>
|
|
The <a href=
|
|
"https://docs.oracle.com/javase/tutorial/java/annotations/index.html">Oracle Javadoc
|
|
tutorial</a> is a good, but somewhat long, <a href=
|
|
"https://docs.oracle.com/javase/tutorial/java/annotations/index.html">introduction
|
|
to Javadoc</a>. A brief summary of the formatting and tags can be found in <a href=
|
|
"https://docs.oracle.com/javase/tutorial/java/annotations/predefined.html">
|
|
the reference</a>.
|
|
<p>It's recommended that Java packages contain a <a href=
|
|
"https://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#packagecomment"><code>
|
|
package-info.java</code></a> file to contain any needed package-level documentation. It can
|
|
also contain any <a href=
|
|
"https://docs.oracle.com/javase/tutorial/java/annotations/index.html">annotations</a> you
|
|
want to apply to all classes in the package. If you don't have any annotations you want to
|
|
include, please include</p>
|
|
<div class="wide">
|
|
<code>@edu.umd.cs.findbugs.annotations.DefaultAnnotation(value={})</code>
|
|
</div>
|
|
<p>which helps some
|
|
of our build systems minimize recompilation. (For more on that annotation, see <a href=
|
|
"https://javadoc.io/static/com.github.spotbugs/spotbugs-annotations/3.1.7/edu/umd/cs/findbugs/annotations/DefaultAnnotation.html">
|
|
here</a>)</p>
|
|
<p>Previously, we used <code>package.html</code> files for this. It's not a high priority to
|
|
replace existing <code>package.html</code> files, but new packages should include a
|
|
<code>package-info.java</code> copied from <code>java/package-info.java</code> instead, see
|
|
above.</p>
|
|
|
|
<p>A nice discussion of how to use the "deprecated" label in documentation is available on
|
|
the <a href=
|
|
"https://docs.oracle.com/en/java/javase/11/core/enhanced-deprecation1.html">"How
|
|
and When To Deprecate APIs" page</a>.</p>
|
|
|
|
<h3 id="html">HTML in Javadoc</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>We run the <code>ant scanhelp</code> job during <a href=
|
|
"ContinuousIntegration.shtml">integration</a> to keep errors from accumulating; you can run
|
|
that on your own changes to the code to get feedback early.</p>
|
|
|
|
<p>The rest of this section is hints and tips on HTML 4.01.</p>
|
|
|
|
<p>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 <code>{@literal ...}</code> or
|
|
<code>{@code ...}</code> blocks.</p>
|
|
|
|
<p>Some error messages that can result from this and their translations:</p>
|
|
|
|
<dl>
|
|
<dt>"malformed HTML"</dt>
|
|
|
|
<dt>"bad HTML entity"</dt>
|
|
|
|
<dd>Probable use of &, < or > characters on the indicated line</dd>
|
|
|
|
<dt>"bad use of '>'"</dt>
|
|
|
|
<dd>
|
|
Probably using '>' as a character, e.g. A -> B. If so, replace with "&gt;" or
|
|
wrap it with <code>@literal</code> as in
|
|
|
|
<pre style="font-family: monospace;">
|
|
{@literal 0.0 -> 1.0.}
|
|
</pre> and
|
|
|
|
<pre style="font-family: monospace;">
|
|
opcodes {@code <opc, string description>} via
|
|
</pre>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p>Definitely use <code>@code{...}</code> in Javadoc comments instead of trying to provide HTML-style
|
|
elements like <tt> and <code>, as they won't format correctly.</p>
|
|
|
|
<p>You also have to (sometimes) end your paragraph tags to start another type of element,
|
|
e.g. lists:</p>
|
|
|
|
<pre style="font-family: monospace;">
|
|
* 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>
|
|
</pre>Note that HTML 4.01 wants paragraph tags to be ended with </p>, and that you can't have
|
|
a list inside a paragraph.
|
|
<p>Finally, note that this Javadoc line is malformed:</p>
|
|
|
|
<pre style="font-family: monospace;">
|
|
* @param foo
|
|
</pre>because it doesn't include any explanatory text. The line should include explanatory text:
|
|
|
|
<pre style="font-family: monospace;">
|
|
* @param foo holds the latest Bar instance
|
|
</pre>
|
|
<h3 id="inherit">Inheriting Javadoc comments</h3>
|
|
|
|
<p>When you write a method that overrides a method (or signature) in a superclass, you should
|
|
always use the <code>@Override</code> annotation to indicate that:</p>
|
|
|
|
<pre style="font-family: monospace;">
|
|
@Override
|
|
public void methodName() {
|
|
// doing something
|
|
}
|
|
</pre>
|
|
<p>If the method is similar enough to the superclass method, you can just "inherit" the
|
|
Javadoc from the superclass:</p>
|
|
|
|
<pre style="font-family: monospace;">
|
|
/**
|
|
* {@inheritDoc}
|
|
*/
|
|
@Override
|
|
public void methodName() {
|
|
// doing something
|
|
}
|
|
</pre>
|
|
<p>(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!)</p>
|
|
|
|
<p>You can add or replace some of the documentation, e.g.</p>
|
|
|
|
<div class="wide"><pre style="font-family: monospace;">
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* This implementation uses the ReallyMarvelous algorithm for improved speed.
|
|
*/
|
|
@Override
|
|
public void methodName() {
|
|
// doing something
|
|
}
|
|
</pre></div>
|
|
|
|
<p>General comments add to the documentation from the superclass; @param and @return tags
|
|
replace the documentation from the superclass.</p>
|
|
|
|
<h3 id="missing">Reducing the Number of Missing Comments</h3>
|
|
|
|
<p>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.</p>
|
|
|
|
<p>CI may fail if invalid JavaDoc is uploaded.</p>
|
|
|
|
<h2>UML and UmlGraph for Developers</h2>
|
|
<p>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 <a href=
|
|
"https://www.visual-paradigm.com/guide/uml-unified-modeling-language/uml-class-diagram-tutorial/">UML
|
|
Class Diagram Tutorial</a>. For more detail, please see <a href=
|
|
"http://web.archive.org/web/20110704185440/http://atlas.kennesaw.edu/~dbraun/csis4650/A&D/UML_tutorial/class.htm">
|
|
Atlas UML course</a> or <a href="http://web.archive.org/web/20110903065325/http://edn.embarcadero.com:80/article/31863">Embarcadero
|
|
Software introduction</a>.</p>
|
|
<p>Our Ant Javadoc processing makes basic UML class diagrams automatically. For an example,
|
|
see the class diagram embedded in <a href="https://www.jmri.org/JavaDoc/doc/jmri/Sensor.html">Sensor
|
|
interface Javadoc</a>. For a more complex example see the class diagram in the <a href=
|
|
"https://www.jmri.org/JavaDoc/doc/jmri/jmrit/progsupport/ProgModeSelector.html">ProgModeSelector
|
|
class Javadoc</a>.</p>
|
|
|
|
<p>You can also define custom UML diagrams using <a href="https://plantuml.com">PlantUML</a>.
|
|
For an example of the source syntax to define state and sequence diagrams, see the</p>
|
|
<div class="wide"><code>
|
|
<a href=
|
|
"https://github.com/JMRI/JMRI/blob/master/java/src/jmri/jmrix/lenz/XNetProgrammer.java#L32">java/src/jmri/jmrix/lenz/XNetProgrammer.java</a>
|
|
</code>
|
|
</div>
|
|
<p>file. The resulting diagrams are visible in its <a href=
|
|
"https://www.jmri.org/JavaDoc/doc/jmri/jmrix/lenz/XNetProgrammer.html">Javadoc output</a>.</p>
|
|
|
|
<p>PlantUML can also be used for standalone diagrams, c.f. <a href=
|
|
"SystemStructure.shtml">the connection sequence diagram</a>. To do this, create a .txt file,
|
|
and then manually process with</p>
|
|
<div class="wide">
|
|
<code>java -jar lib/plantuml.jar help/en/my/file/path/name</code>
|
|
</div>
|
|
<p>A .png with the diagram will be created alongside the source.</p>
|
|
|
|
<h2>Processing</h2>
|
|
The standard JMRI Ant build provides three documentation targets:
|
|
<dl>
|
|
<dt>javadoc</dt>
|
|
|
|
<dd>Create the text Javadocs in the local doc/ directory. Open doc/index.html for
|
|
access.</dd>
|
|
|
|
<dt>javadoc-uml</dt>
|
|
|
|
<dd>Create the UML diagrams and Javadocs in the local doc/ directory. Open doc/index.html
|
|
for access.</dd>
|
|
|
|
<dt>uploadjavadoc</dt>
|
|
|
|
<dd>
|
|
Upload the current documentation in the local doc/ directory to the jmri.org website.
|
|
This is done automatically by the <a href="ContinuousIntegration.shtml">CI system</a>, so
|
|
you generally don't have to deal with it.
|
|
</dd>
|
|
</dl>
|
|
<!--#include virtual="/help/en/parts/Footer.shtml" -->
|
|
</div>
|
|
<!-- closes #mainContent-->
|
|
</div>
|
|
<!-- closes #mBody-->
|
|
<script src="/js/help.js"></script>
|
|
</body>
|
|
</html>
|