RFR: 8231186: Replace html tag <code>foo</code> with javadoc tag {@code foo} in java.base
Brent Christian
brent.christian at oracle.com
Wed Sep 18 23:13:08 UTC 2019
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
>>>
More information about the core-libs-dev
mailing list