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

[Joe Darcy]

Hi Pavel,

Looks fine in general, assuming the change to Class.java renders 
correctly in output.

Thanks,

-Joe

On 4/7/2020 8:28 AM, Pavel Rappo wrote:
> 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
>>