Skip to content
Permalink
Browse files

more on deprecations

  • Loading branch information...
bobjacobsen committed Sep 22, 2018
1 parent 9577347 commit d7e11a57483321f99a076cd63a8399c39e619e22
Showing with 84 additions and 33 deletions.
  1. +47 −26 help/en/html/doc/Technical/Javadoc.shtml
  2. +37 −7 help/en/html/doc/Technical/RP.shtml
@@ -54,15 +54,20 @@
"http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#documentationcomments">
the reference</a>.

<p>Traditionally, the Java packages in JMRI have used
<code>package.html</code> files to contain any needed
package-level documentation. It's now <a href=
<p>
It's <a href=
"http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#packagecomment">
recommended</a> that any significant Java package contain a
<a href=
"http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#packagecomment">
<code>package-info.java</code></a> file for this. Only a few
of these have been included in JMRI so far, and it's not a
<code>package-info.java</code></a> file
to contain any needed
package-level documentation.
(It can also contain any
<a href="http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html">annotations</a>
you want to apply to all classes in the package)
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
@@ -81,27 +86,25 @@
display properly when somebody wants to understand your code,
so it's in your interest to get the Javadoc comments
right.</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>For example, you have to properly handle &amp; and &lt;
character, e.g. to show a generic type. To do that, place the
test in {@literal ...} or {@code ...} blocks.</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
* &lt;p&gt;
* Some more text.
* &lt;p&gt;
* Last text, start list. Note end-paragraph tag.
* &lt;/p&gt;&lt;ul&gt;
* &lt;li&gt;List item
* &lt;/ul&gt;
</pre>
Note that HTML 4.01 wants paragraph tags to be ended with
&lt;/p&gt;, and that you can't have a list inside a paragraph.
<p>The rest of this section is hints and tips on HTML 4.01.

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

<p>Some error messages and their translations:</p>
<p>Some error messages that can result from this and their translations:</p>

<dl>
<dt>"malformed HTML"</dt>
@@ -116,7 +119,24 @@ Note that HTML 4.01 wants paragraph tags to be ended with
<dd>Probably using '&gt;' as a character, e.g. A -&gt; B.
If so, replace with "&amp;gt;" or wrap the line with
@literal</dd>
</dl>Finally, note that this Javadoc line is malformed:
</dl>

<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
* &lt;p&gt;
* Some more text.
* &lt;p&gt;
* Last text, start list. Note end-paragraph tag.
* &lt;/p&gt;&lt;ul&gt;
* &lt;li&gt;List item
* &lt;/ul&gt;
</pre>
Note that HTML 4.01 wants paragraph tags to be ended with
&lt;/p&gt;, and that you can't have a list inside a paragraph.

<p>Finally, note that this Javadoc line is malformed:
<pre style="font-family: monospace;">
* @param foo
</pre>
@@ -147,7 +167,8 @@ should include explanatory text:
// doing something
}
</pre>
<p>(I there's no Javadoc in the superclass, consider adding your comments there instead of on your new method and inheriting them;
<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> You can add or replace some of the documentation, e.g.
<pre style="font-family: monospace;">
@@ -159,14 +159,40 @@
As development proceeds, sometimes
old ways of doing things have to be replaced by new ways. In
many cases, you can just change all the using code in our
repository, and move forward. For general interfaces that
repository, and move forward.
For general interfaces that
might be used externally to JMRI, such as in scripts and
CATS, it can be good to leave the old interface in place for
CATS, we prefer to leave the old interface in place for
a while, marking it as "deprecated" so that people can
discover that it will eventually go away. After a suitable
number of release cycles, the deprecated interface can then
be removed.
discover that it will eventually go away. The sequence is then:
<ul>
<li>Write the new methods.
<li>Mark the old methods with @deprecated and @Deprecated (see below).
<p>Note that if you mark an interface or super-class (i.e. abstract)
class or method
as deprecated, you should also mark all implementations of it as
deprecated. That way, they won't themselves show as deprecations to fix,
but code that uses them will.
<li>Over time, remove all JMRI uses of these deprecated classes and/or methods
until the deprecations report is clean.
You can either compile locally
with <code>ant ci-deprecations</code> to check this, or look at the
<a href="http://jmri.tagadab.com/jenkins/job/Development/job/Deprecations/lastBuild/warnings4Result/">Jenkins CI report</a>
(click the Types tab) to check the JMRI/JMRI master branch.
Don't forget to also migrate the
Jython sample scripts!

<li>Once JMRI itself is clean (enough), start generating warnings for users
(especially scripting users) by adding:
<pre style="font-family: monospace;">
jmri.util.Log4JUtil.warnOnce(log, "Deprecated doStuff() method called. You should replace this with with a call to doBetterStuff()");
</pre>
<li>Wait an appropriate length of time; the more visible the class or method,
the longer to wait. Things that were in scripts should wait at least two
production releases.
<li>Remove the deprecated methods and their tests.
</ul>

<p>Note that a deprecated interface is meant to still work.
Deprecated should only mean that you can't count on the
deprecated interface working in the future, so that it would
@@ -177,7 +203,7 @@
additional information. A nice discussion of the
technicalities is <a href=
"http://download.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/deprecation.html">
here</a>. We recommend using both of them like this:</p>
here</a>. We strongly recommend using both of them like this:</p>
<pre style="font-family: monospace;">
/**
* (Other Javadoc comments)
@@ -187,7 +213,11 @@
</pre>
where the line contains the version in which the deprecation
is applied. That lets you easily know how long ago it was
deprecated.
deprecated. (There's a better way to do this in Java 9, but
JMRI still has to compile under Java 8 so please don't use that; see the
<a href="TechRoadMap.shtml">release roadmap</a>
for background)


<p>You may want to work with the deprecation checks "on"
during compilation. To do that, change this line of

0 comments on commit d7e11a5

Please sign in to comment.
You can’t perform that action at this time.