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

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Alan Bateman
On 19/04/2017 13:54, 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.
>
> 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
The serviceability-dev mailing list is the best place to discuss the
debugger API.

However, what you have looks okay. I think I would use the opportunity
to replace "The JDI" with just "JDI" in the second and third paragraphs.

-Alan
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung

> On Apr 19, 2017, at 5:54 AM, Magnus Ihse Bursie <[hidden email]> 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.
>
> 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


Moving the content from jdi-overview.html to module-info.java is the right choice.

Nit: if you don’t mind, can you replace <code>…</code> with {@code …}

Otherwise, looks fine.

The following sentence reads a little strange to me that contains a couple of “…”.
I just want to point it out and we should leave it as is.

  36  * The JDI also provides explicit control over a virtual machine's execution.
  37  * The ability to suspend and resume threads, and to set breakpoints,
  38  * watchpoints, ... Notification of exceptions, class loading, thread
  39  * creation... The ability to inspect a suspended thread's state, local
  40  * variables, stack backtrace…

Mandy
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

David Holmes
In reply to this post by Alan Bateman
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&trade; Debug Interface (JDI) is a high level Java API
providing

The first line should read "Debug" not "Debugger".

Contrary to what Alan suggested (sorry Alan!) I think plain "JDI" should
be replaced by "The JDI".

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
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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&trade; 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
>>

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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&trade; 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
>>>
>
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

Mandy Chung
In reply to this post by Magnus Ihse Bursie

> On Apr 20, 2017, at 12:57 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>
>
> http://cr.openjdk.java.net/~ihse/JDK-8178037-fix-obsolete-overview-files/webrev.02/

Looks good.

Mandy
Loading...