RFR: JDK-8178037 Move information from jdi-overview.html into jdk.jdi module-info.java

[David Holmes]

On 20/04/2017 5:57 PM, Magnus Ihse Bursie wrote:
> On 2017-04-20 04:21, David Holmes wrote:
>> On 19/04/2017 10:54 PM, Magnus Ihse Bursie wrote:
>>> With JDK-8172312, the file src/jdk.jdi/share/classes/jdi-overview.html
>>> is no longer included in the generated documentation. The information
>>> provided by that file should move to
>>> src/jdk.jdi/share/classes/module-info.java instead.
>>
>> Looks good, but highlighted an error with the existing text:
>>
>>   /**
>>    * Defines the Java Debugger Interface.
>> +  * <p>
>> +  * The Java™ Debug Interface (JDI) is a high level Java API
>> providing
>>
>> The first line should read "Debug" not "Debugger".
>
> Good catch.
>
> I really didn't plan to make any editorial changes in this review, only
> to move the contents to a place were it was once again included.
> However, the text was apparently in need of some freshing up, so I tried
> to fix what was pointed out.
>
>>
>> Contrary to what Alan suggested (sorry Alan!) I think plain "JDI"
>> should be replaced by "The JDI".
>
> I love it when I get conflicting reviews! ;-)
>
> I'm sorry Dave, I'm afraid I can't do that. :-) "The JDI" just sounds
> weird, and that's not how acronyms are typically referred to. So I've
> sided with Alan here. If you don't agree, I'll back out that change and
> you can fight it out by yourselves. :)

It depends on the exact nature of the acronym. If you wrote this out you 
would say "The Java Debug Interface .." hence you should say "The JDI ...".

:)

Cheers,
David
-----

> And Mandy: I agree with the weird ellipses. I changed that to "etc.",
> which I think captures the intent that the list was not exhaustive.
>
> Here is an updated review. It fixes the "Debugger" in the title, "The
> JDI" -> "JDI" in two places, "..." -> "etc." and <code> -> {@code}.
>
> http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.02/
>
>
> /Magnus
>
>>
>> Thanks,
>> David
>>
>>> I also took the liberty of removing a bunch of other overview.html files
>>> that are not included in the Javadoc anymore. They provided no real
>>> informational value, and what text they contained is already expressed
>>> similarly or better in the corresponding module-info.java files instead.
>>>
>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8178037
>>> WebRev:
>>> http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.01
>>>
>>>
>>>
>>> /Magnus
>>>
>