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

[Brent Christian]

Hi, Julia

I found one more empty .diff:

http://cr.openjdk.java.net/~jboes/webrevs/8231186/webrev.02/src/java.base/share/classes/java/util/regex/Matcher.java.sdiff.html

In the .patch file, I see that there are changes to:

ResourceBundle.java, Calendar.java, and SecurityManager.java

so it seems that somehow not all the changes were put into Sdiffs.  Strange!

--

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)}

--
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.  I found the following examples in the webrev:

java/io/PipedInputStream.java:

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

  300      *           <a href="#BROKEN"> {@code broken}</a>, closed,

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

  421      *          <a href="#BROKEN"> {@code broken}</a>.

--

java/io/PipedReader.java:

  229      *          <a href=PipedInputStream.html#BROKEN> {@code 
broken}</a>,

  286      *                  <a href=PipedInputStream.html#BROKEN> 
{@code broken}</a>,

  334      *                  <a href=PipedInputStream.html#BROKEN> 
{@code broken}</a>,

--

java/io/PipedWriter.java:

  116      *          <a href=PipedOutputStream.html#BROKEN> {@code 
broken}</a>,

  146      *          <a href=PipedOutputStream.html#BROKEN>{@code 
broken}</a>,


Looks good otherwise.

Thanks,
-Brent

On 9/18/19 11:37 AM, Brent Christian wrote:
> FWIW, I also noticed this for
> 
> http://cr.openjdk.java.net/~jboes/webrevs/8231186/webrev.02/src/java.base/share/classes/java/lang/SecurityManager.java.sdiff.html 
> 
> 
> -B
> 
> On 9/18/19 11:32 AM, naoto.sato at oracle.com wrote:
>> Hi Julia,
>>
>> This is not a comment to changes you've made, but the webrev seems 
>> missing some diffs, e.g.,
>>
>> http://cr.openjdk.java.net/~jboes/webrevs/8231186/webrev.02/src/java.base/share/classes/java/util/Calendar.java.sdiff.html 
>>
>> http://cr.openjdk.java.net/~jboes/webrevs/8231186/webrev.02/src/java.base/share/classes/java/util/ResourceBundle.java.sdiff.html 
>>
>>
>> Not checked all, so there may be some other blank diffs. Could be a 
>> bug in the tool.
>>
>> Naoto
>>
>> On 9/18/19 8:47 AM, Julia Boes wrote:
>>> Hi,
>>>
>>> This change replaces the HTML code tag with the equivalent javadoc 
>>> tag in the java.base module as such:
>>>
>>> <code>foo</code> becomes {@code foo}
>>>
>>> Ignored are any code tags that enclose other HTML or javadoc tags or 
>>> that contain HTML entities, e.g. character codes.
>>>
>>>
>>> Examples (after change):
>>>
>>> java.base/share/classes/java/nio/charset/spi/CharsetProvider.java
>>>
>>> 51 * ignored.  The comment character is {@code '#'} 
>>> (<code>'\u0023'</code>); on
>>>
>>> java.base/share/classes/java/io/File.java
>>>
>>> 625 * <code>new File(this.{@link #getCanonicalPath})</code>.
>>>
>>>
>>> I reviewed the change with specdiff and doccheck on the java.base 
>>> module, neither flagged any differences or errors. I also reviewed 
>>> the javadoc of some classes manually but did not do an extensive 
>>> manual review.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8231186
>>>
>>> Webrev: http://cr.openjdk.java.net/~jboes/webrevs/8231186/webrev.02/
>>>
>>>
>>> The copyright year will be updated before generating the changeset.
>>>
>>> Regards,
>>>
>>> Julia
>>>