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

[Pavel Rappo]

Thanks, Joe. I presume you mean me changing this

    * <code>@</code>{@code interface}

to this

    * {@code @interface}

Right? If so, then it renders the same way, and the `@interface` does not
confuse the Standard Doclet. After JDK-8241780 "Allow \n@ inside inline tags"
has been done and dusted we'll never have to think about that ever again.

> On 7 Apr 2020, at 20:23, Joe Darcy <joe.darcy at oracle.com> wrote:
> 
> 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
>>>