Re: RFR: 8231186: Replace html tag foo with javadoc tag {@code foo} in java.base

[Roger Riggs]

Hi Julia,

Did youuse webrev.ksh or the git-webrev available with Skara?
If the later, then it can/should be reported and fixed.

Roger


On 9/20/19 6:22 AM, Julia Boes wrote:

Hi,

Thanks for noticing the glitch in the sdiffs, Naoto and Brent. I see that there is indeed an issue with the webrev script and I'm looking into a workaround.

The following classes are affected:

src/java.base/share/classes/java/lang/SecurityManager.java

src/java.base/share/classes/java/util/Calendar.java

src/java.base/share/classes/java/util/ResourceBundle.java

src/java.base/share/classes/java/util/regex/Matcher.java

java/io/InputStream.java:

 243      * <p> The {@code read(b,} {@code off,} {@code len)} method

I believe this can be simplified to:

{@code read(b, off, len)}

--

   Changed!

Here's something I found examples of in several places, for instance in PipedInputStream.java:

 195      * @exception IOException If the pipe is <a href="#BROKEN"> {@code broken}</a>,

Here we have a link written out in HTML, with {@code} used within the displayed text of the link.  This would typically be done instead by using a @link tag, as on the next line:

 196      *          {@link #connect(java.io.PipedOutputStream) unconnected},

Peeking at the generated HTML, AFAICT the @link tag takes care of generating the <code></code> styling in the generated HTML.  I think it's worth considering converting these <a href=...>'s to @link, either now or as future work.

   Brent, I can make this change but can the @link tag link to a HTML
   id? It's not mentioned in the documentation
https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#link.

I expected occurrences of '<tt>' would need changes as well, but it appears there aren't any in java.base (some previous effort cleaned this up, I guess).

    That's right, there are none in java.base.

I recall thinking that many of the <code> should actually be changed to @link since use of <code> suggested ancient times before @link became available.

But "Perfect is the enemy of good".

    I agree, if that's ok I would leave that as future work ;)

Regards,
Julia