JDK 15 RFR of JDK-8237805: Use inline @jls @jvms in core libs where appropriate

[Joe Darcy]

Hello,

I changed the one "§" to "section" and re-flowed the paragraphs 
with long lines.

I believe the existing use of

     (Lorem ipsum ... aliqua.)

is correct rather than

     (Lorem ipsum ... aliqua).

Thanks,

-Joe

On 2/13/2020 3:14 AM, Pavel Rappo wrote:
> @Joe, I noticed you changed "section" to the § entity in one place. In
> other places it is still in prose, i.e. "section" and "sections". I think
> whatever we choose we should try to use it consistently. I built the API docs
> and checked that everything renders as expected. (Links are 404, obviously,
> since they refer to a not-yet-released version.)
>
>    This change looks good to me.
>
> @Daniel, not sure how reputable these sources are. Still, worth a quick look:
>
>    https://www.grammarly.com/blog/period/
>    https://www.chicagomanualofstyle.org/qanda/data/faq/topics/Punctuation/faq0040.html
>
> I was thinking that the issue you were referring to was about differences
> between American English and British English. However, after re-reading the
> links above I now believe that I misremembered. Those differences apply to full
> stops (periods) and quotation marks, not full stops and parentheses.
>
> -Pavel
>
>> On 13 Feb 2020, at 10:07, Daniel Fuchs <daniel.fuchs at oracle.com> wrote:
>>
>> Hi Joe,
>>
>> Nits:
>>
>> http://cr.openjdk.java.net/~darcy/8237805.0/src/java.base/share/classes/java/lang/invoke/MethodHandle.java.frames.html
>> line 226
>>
>> http://cr.openjdk.java.net/~darcy/8237805.0/src/java.base/share/classes/java/lang/invoke/MethodHandleInfo.java.frames.html
>> line 46
>>
>> http://cr.openjdk.java.net/~darcy/8237805.0/src/java.base/share/classes/java/lang/invoke/MethodHandles.java.frames.html
>> lines 505 and 518
>>
>> http://cr.openjdk.java.net/~darcy/8237805.0/src/java.base/share/classes/java/lang/invoke/MethodType.java.frames.html
>> line 95
>>
>> wouldn't it be more correct to have the full stop
>> after the closing parenthesis, rather than before?
>> (no need for new webrev)
>>
>> best regards,
>>
>> -- daniel
>>
>> On 13/02/2020 04:47, Joe Darcy wrote:
>>> Hello,
>>> Inline forms of the @jls and @jvms javadoc tags are now available (JDK-8235926). I made a pass over the files in java.base to take advantage of the new feature:
>>>      http://cr.openjdk.java.net/~darcy/8237805.0/
>>> Thanks,
>>> -Joe