RFR [15] 8242230: Whitespace typos, relaxed javadoc, formatting

[Pavel Rappo]

Hi Ivan,

> On 7 Apr 2020, at 09:11, Ivan Gerasimov <ivan.gerasimov at oracle.com> wrote:
> 
> Hi Pavel!
> 
> A couple of comments.
> 
> 1)
> java/util/logging/Formatter.java
> 
> This has one extra open curly brace:
> 
> "{{@literal <digit>}"

The leftmost curly brace is not a part of the "literal" inline tag, but rather
a part of the message format string. Have a look at the method that the comment
belongs to. Note what that method is looking for in a message string.

> 2)
> grep finds some more typos of the same kind that you've spotted.
> 
> a)  rgrep '^[ ]*\*'|grep ' ,'|less
> 
> This find number of potential typos.  For example, the javadoc for VarHandle [1] has 53 occurrances of space-before-comma.  A few more are found in j.l.Thread, j.io.DataOutput, j.l.String, etc.
> 
> b)  rgrep '^[ ]*\*'|grep '\w- '|less
> 
> This find the word 'network' broken with a hyphen at [2] and also in share/classes/sun/net/util/IPAddressUtil.java
> 
> (I only searched under src/java.base)

Thanks. I've included some of those: true positive, non-controversial,
and significant cases where I believe I sufficiently understood context.

For instance, I was not sure if I reliably grasped the applicability of the
"statically represented using varargs" phrase used widely across the VarHandle
type. It looks like that phrase was blankedly added to @return and @return tags.
So, I left it out for now.

The updated patch can be found here:

    http://cr.openjdk.java.net/~prappo/8242230/webrev.01/

***

Some of the cases this patch addresses suggest that we might need to do
something about how the Standard Doclet treats newline characters in source
files. More often than not, newline characters are purely to control the width
of the source lines. When carried over to the output, they may produce
undesirable effects. Punctuation marks and contents of the Standard Doclet tags
may be affected.

That problem [1] is neither new nor trivial to address. Still, we should add
something to the Standard Doclet Specification [2].

I'm not sure what we can do about it now other than work around the current
behavior where it is significant.

-Pavel

P.S. CC'ing to javadoc-dev at openjdk.java.net

-------------------------------------------------------------------------------
[1] https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap
[2] https://docs.oracle.com/en/java/javase/14/docs/specs/javadoc/doc-comment-spec.html

> With kind regards,
> 
> Ivan
> 
> [1] https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/lang/invoke/VarHandle.html
> 
> [2] https://docs.oracle.com/en/java/javase/14/docs/api/java.base/java/net/Inet4Address.html
> 
> On 4/6/20 11:28 AM, Pavel Rappo wrote:
>> Hello,
>> 
>> Please review the change for https://bugs.openjdk.java.net/browse/JDK-8242230:
>> 
>>   http://cr.openjdk.java.net/~prappo/8242230/webrev.00/
>> 
>> This is a documentation cleanup. There are no code changes involved,
>> and the changes in documentation are mostly trivial.
>> 
>> The following packages are affected:
>> 
>>     java.lang,
>>     java.text,
>>     java.util,
>>     java.util.logging,
>>     javax.lang.model.util,
>>     jdk.internal.reflect
>> 
>> -Pavel
>> 
> -- 
> With kind regards,
> Ivan Gerasimov
>