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

[Magnus Ihse Bursie]

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

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