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.da...@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.gerasi...@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-...@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
>>>
