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

[Joe Darcy]

Hi Pavel,

On 4/7/2020 1:07 PM, Pavel Rappo wrote:
> Thanks, Joe. I presume you mean me changing this
>
>      * <code>@</code>{@code interface}
>
> to this
>
>      * {@code @interface}

Correct.


>
> 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.

I didn't double-check the history, but I may have added

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

way back when and if note in this particular instance I recall that kind 
of javadoc contortion was necessary at the time to get (almost) the 
desired effect.

Thanks,

-Joe

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