Quantcast

RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

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

RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Magnus Ihse Bursie
This patch will solve three issues that I (unfortunately) filed as
separate issues, but that shares a common solution. The three issues are:
  JDK-8178038 Copy jdwp-protocol.html to proper location
  JDK-8178039 Copy jvmti.html to proper location
  JDK-8178316 Add JVM-MANAGEMENT-MIB.mib to
jdk/src/java.management/share/specs/

This patch will also solve this in a general way, to start preparing for
JDK-8177434 (Copy specifications from module specs directory to docs image).

Bug descriptions:

https://bugs.openjdk.java.net/browse/JDK-8178038 Copy jdwp-protocol.html
to proper location
After JDK-8172312, the copy of jvmti.html into docs/platform/jvmti will
stick out like a sore thumb. It should be moved to the new location
designed by JEP 299, in docs/specs.

https://bugs.openjdk.java.net/browse/JDK-8178039 Copy jvmti.html to
proper location
After JDK-8172312, the copy of jvmti.html into docs/platform/jvmti will
stick out like a sore thumb. It should be moved to the new location
designed by JEP 299, in docs/specs.

https://bugs.openjdk.java.net/browse/JDK-8178316 Add
JVM-MANAGEMENT-MIB.mib to jdk/src/java.management/share/specs/
The file JVM-MANAGEMENT-MIB.mib have unfortunately been stored in the
closed sources. This was an oversight, and it should be moved to open
sources.

The file will follow the new structure of JEP 299 and be put in
java.management/share/specs/, and copied to docs/specs during build.

WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Erik Joelsson
Looks good.

Nit: Javadoc.gmk:358-360 only indented 2 spaces for continuation. Same
goes for 390-393, but you didn't actually touch those lines.

/Erik


On 2017-04-19 14:36, Magnus Ihse Bursie wrote:

> This patch will solve three issues that I (unfortunately) filed as
> separate issues, but that shares a common solution. The three issues are:
>  JDK-8178038 Copy jdwp-protocol.html to proper location
>  JDK-8178039 Copy jvmti.html to proper location
>  JDK-8178316 Add JVM-MANAGEMENT-MIB.mib to
> jdk/src/java.management/share/specs/
>
> This patch will also solve this in a general way, to start preparing
> for JDK-8177434 (Copy specifications from module specs directory to
> docs image).
>
> Bug descriptions:
>
> https://bugs.openjdk.java.net/browse/JDK-8178038 Copy
> jdwp-protocol.html to proper location
> After JDK-8172312, the copy of jvmti.html into docs/platform/jvmti
> will stick out like a sore thumb. It should be moved to the new
> location designed by JEP 299, in docs/specs.
>
> https://bugs.openjdk.java.net/browse/JDK-8178039 Copy jvmti.html to
> proper location
> After JDK-8172312, the copy of jvmti.html into docs/platform/jvmti
> will stick out like a sore thumb. It should be moved to the new
> location designed by JEP 299, in docs/specs.
>
> https://bugs.openjdk.java.net/browse/JDK-8178316 Add
> JVM-MANAGEMENT-MIB.mib to jdk/src/java.management/share/specs/
> The file JVM-MANAGEMENT-MIB.mib have unfortunately been stored in the
> closed sources. This was an oversight, and it should be moved to open
> sources.
>
> The file will follow the new structure of JEP 299 and be put in
> java.management/share/specs/, and copied to docs/specs during build.
>
> WebRev:
> http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01
>
> /Magnus

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Mandy Chung
In reply to this post by Magnus Ihse Bursie

> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote:
>
> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01

 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \
 370     FILES := $(JDWP_PROTOCOL), \
 371     DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \
 372 ))

Is there any reason why jdwp-protocol.html is not copied to the “specs” directory?

docs-docs-specs copies specs to jdk docs.  I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing.

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Mandy Chung

> On Apr 19, 2017, at 3:54 PM, Mandy Chung <[hidden email]> wrote:
>
>
>> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote:
>>
>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01
>
> 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html

One more thing: jdwp-protocol belongs to jdk.jdwp.agent module.
It would be nice if Gensrc-jdk.jdi.gmk can be cleaned up.

Mandy

> 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \
> 370     FILES := $(JDWP_PROTOCOL), \
> 371     DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \
> 372 ))
>
> Is there any reason why jdwp-protocol.html is not copied to the “specs” directory?
>
> docs-docs-specs copies specs to jdk docs.  I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing.
>
> Mandy

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Magnus Ihse Bursie
In reply to this post by Mandy Chung


On 2017-04-20 00:54, Mandy Chung wrote:

>> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote:
>>
>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01
>   368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
>   369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \
>   370     FILES := $(JDWP_PROTOCOL), \
>   371     DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \
>   372 ))
>
> Is there any reason why jdwp-protocol.html is not copied to the “specs” directory?
Yes, there is. This document is only part of the jdwp specification.
This is dynamically generated. The rest of the jdwp specification is
static. I have a prototype that, in light of JEP 299, copies the rest of
the specification to "specs/jdwp", but at the moment it's unclear if
that's going to get into JDK 9. Nevertheless, I think it is prudent to
prepare for this structure.

> docs-docs-specs copies specs to jdk docs.  I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing.
You mean docs-jdk-specs?

While there is a superficial similarity between "docs-jdk" and
"docs-javase", there's a difference in purpose. The latter is only
created for a special-purpose formal API verification, and is not
supposed to be shipped. This means that it's not built by e.g.
"docs-image". I assumed that only the API would be needed for that.

/Magnus

>
> Mandy

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Magnus Ihse Bursie
In reply to this post by Mandy Chung
On 2017-04-20 01:11, Mandy Chung wrote:
>> On Apr 19, 2017, at 3:54 PM, Mandy Chung <[hidden email]> wrote:
>>
>>
>>> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote:
>>>
>>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01
>> 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
> One more thing: jdwp-protocol belongs to jdk.jdwp.agent module.
> It would be nice if Gensrc-jdk.jdi.gmk can be cleaned up.
I agree that it would be nice if Gensrc-jdk.jdi.gmk can be cleaned up.
Unfortunately it's a bit tangled up right now, and a proper solution
might be too radical for this change. But let's see if we can sort this
out, perhaps with your module expertise a solution is possible.

We need to gensrc three files:
1) $(SUPPORT_OUTPUTDIR)/headers/jdk.jdwp.agent/JDWPCommands.h
2) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/com/sun/tools/jdi/JDWP.java
3) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html

1 and 2 are being created by the same call to the build tool, and 3 is
created by a separate call. I'm not sure if this is possible to change.
It looks like it might.

1 already belongs to jdk.jdwp.agent, and 3 could easily be moved there.
The problem is 2, which is needed when compiling the jdk.jdi module.

I have two suggestions, but I don't know if either of them is possible:
1) Move the JDWP.java file to jdk.jdwp.agent, and make sure it's
properly exported from jdk.jdwp.agent to jdk.jdi. (From my point of
view, this seems like the logical thing to do.) In this case, the entire
gensrc:ing could move to jdk.jdwp.agent, and possibly even into a single
call to the build tool to generate all three files.

2) Split the gensrc into one for jdk.jdwp.agent that generated 1 and 3,
and one for jdk.jdi that generates 2. It might require us to generate a
dummy 2 and 1 that are just thrown away, if the tool cannot be told not
to generate both 1 and 2 at the same time.

/Magnus

>
> Mandy
>
>> 369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \
>> 370     FILES := $(JDWP_PROTOCOL), \
>> 371     DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \
>> 372 ))
>>
>> Is there any reason why jdwp-protocol.html is not copied to the “specs” directory?
>>
>> docs-docs-specs copies specs to jdk docs.  I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing.
>>
>> Mandy

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Alan Bateman
On 20/04/2017 08:37, Magnus Ihse Bursie wrote:
> :
>
> I have two suggestions, but I don't know if either of them is possible:
> 1) Move the JDWP.java file to jdk.jdwp.agent, and make sure it's
> properly exported from jdk.jdwp.agent to jdk.jdi. (From my point of
> view, this seems like the logical thing to do.) In this case, the
> entire gensrc:ing could move to jdk.jdwp.agent, and possibly even into
> a single call to the build tool to generate all three files.
JDWP.java is the debugger side of the wire protocol and so jdk.jdi is
the right module for this class.

I haven't been following this thread closely but are you planning to
move make/data/jdwp/jdwp.spec or the jdwpgen tool? If not then would it
help if this tool were updated with an option to to just generate the
source files for debugger or debuggee side rather than both? That seems
to be your option #2 which I assume would mean running the tool twice.

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Mandy Chung
In reply to this post by Magnus Ihse Bursie

> On Apr 20, 2017, at 12:21 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>
>
>
> On 2017-04-20 00:54, Mandy Chung wrote:
>>> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote:
>>>
>>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01
>>  368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
>>  369 $(eval $(call SetupCopyFiles, COPY_JDWP_PROTOCOL, \
>>  370     FILES := $(JDWP_PROTOCOL), \
>>  371     DEST := $(JAVADOC_OUTPUTDIR)/specs/jdwp, \
>>  372 ))
>>
>> Is there any reason why jdwp-protocol.html is not copied to the “specs” directory?
> Yes, there is. This document is only part of the jdwp specification. This is dynamically generated. The rest of the jdwp specification is static. I have a prototype that, in light of JEP 299, copies the rest of the specification to "specs/jdwp", but at the moment it's unclear if that's going to get into JDK 9. Nevertheless, I think it is prudent to prepare for this structure.
>

Should the specs be organized with modular layout? e.g. docs/specs/$MODULE.
In this case, it would be docs/specs/jdk.jdwp.agent.

Jon - have you considered the specs be organized with modular layout?

>> docs-docs-specs copies specs to jdk docs.  I would expect there will be docs-javase-specs to copy specs from Java SE modules to javase-docs/specs but missing.
> You mean docs-jdk-specs?

Oops.. typo.

>
> While there is a superficial similarity between "docs-jdk" and "docs-javase", there's a difference in purpose. The latter is only created for a special-purpose formal API verification, and is not supposed to be shipped. This means that it's not built by e.g. "docs-image". I assumed that only the API would be needed for that.

Some spec are Java SE such as JNI, JVM TI, JAR file spec that should be included when building "docs-javase" target.  So copying of $MODULE/share/specs to $JAVADOC_OUTPUTDIR/specs should also be done for docs-javase but only the selected Java SE modules.  JDI and JDWP are not Java SE and no need to handle that.

I’m okay if you prefer separating “copying of Java SE specs" for “docs-javase” from this issue.

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Alan Bateman


On 20/04/2017 17:26, Mandy Chung wrote:
> JDI and JDWP are not Java SE and no need to handle that.
>
Just a small correction to this. The JDWP spec is Java SE. JDI is course
JDK-specific, as is the JDWP transport interface.

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Mandy Chung
In reply to this post by Magnus Ihse Bursie

> On Apr 20, 2017, at 12:37 AM, Magnus Ihse Bursie <[hidden email]> wrote:
>
> On 2017-04-20 01:11, Mandy Chung wrote:
>>> On Apr 19, 2017, at 3:54 PM, Mandy Chung <[hidden email]> wrote:
>>>
>>>
>>>> On Apr 19, 2017, at 5:36 AM, Magnus Ihse Bursie wrote:
>>>>
>>>> WebRev: http://cr.openjdk.java.net/~ihse/JDK-8178038-javadoc-specs/webrev.01
>>> 368 JDWP_PROTOCOL := $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
>> One more thing: jdwp-protocol belongs to jdk.jdwp.agent module.
>> It would be nice if Gensrc-jdk.jdi.gmk can be cleaned up.
> I agree that it would be nice if Gensrc-jdk.jdi.gmk can be cleaned up. Unfortunately it's a bit tangled up right now, and a proper solution might be too radical for this change. But let's see if we can sort this out, perhaps with your module expertise a solution is possible.
>
> We need to gensrc three files:
> 1) $(SUPPORT_OUTPUTDIR)/headers/jdk.jdwp.agent/JDWPCommands.h
> 2) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/com/sun/tools/jdi/JDWP.java
> 3) $(SUPPORT_OUTPUTDIR)/gensrc/jdk.jdi/jdwp-protocol.html
>
> 1 and 2 are being created by the same call to the build tool, and 3 is created by a separate call. I'm not sure if this is possible to change. It looks like it might.
>
> 1 already belongs to jdk.jdwp.agent, and 3 could easily be moved there. The problem is 2, which is needed when compiling the jdk.jdi module.
>
> I have two suggestions, but I don't know if either of them is possible:
> 1) Move the JDWP.java file to jdk.jdwp.agent, and make sure it's properly exported from jdk.jdwp.agent to jdk.jdi. (From my point of view, this seems like the logical thing to do.) In this case, the entire gensrc:ing could move to jdk.jdwp.agent, and possibly even into a single call to the build tool to generate all three files.
>

As Alan said, JDWP.java is part of jdk.jdi.  No need to be moved.


> 2) Split the gensrc into one for jdk.jdwp.agent that generated 1 and 3, and one for jdk.jdi that generates 2. It might require us to generate a dummy 2 and 1 that are just thrown away, if the tool cannot be told not to generate both 1 and 2 at the same time.

I checked that build.tool.jdwpgen.Main can be invoked with -doc option only to generate 2 and it can be invoked separately with -include option to generate 1.

Moving 1 and 3 to Gensrc-jdk.jdwp.agent.gmk seems like would work without change to the jdwpgen tool.

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Mandy Chung
In reply to this post by Alan Bateman

> On Apr 20, 2017, at 9:32 AM, Alan Bateman <[hidden email]> wrote:
>
>
>
> On 20/04/2017 17:26, Mandy Chung wrote:
>> JDI and JDWP are not Java SE and no need to handle that.
>>
> Just a small correction to this. The JDWP spec is Java SE. JDI is course JDK-specific, as is the JDWP transport interface.

Thanks for the correction.  In this case, which module should jdwp-protocol.html spec belong to?  Not jdk.jdwp.agent then.

The suggestion of the modular specs layout in the docs bundle may not apply.

Mandy

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Alan Bateman
On 20/04/2017 17:47, Mandy Chung wrote:

> In this case, which module should jdwp-protocol.html spec belong to?  Not jdk.jdwp.agent then.
> The suggestion of the modular specs layout in the docs bundle may not apply.
>
jdwp-protocol.html is the JDWP protocol so it's implemented by both the
debugger and debugee. Typically the debugger sends a command and the
debuggee responds with a reply. There are also event messages that the
target VM/debuggee sends to the debugger. If there is place for Java SE
documentation then it might be best to put it there rather than trying
to put it in jdk.jdi or jdk.jdwp.agent.

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

Re: RFR: JDK-8178038, JDK-8178039, JDK-8178316 Javadoc specs directory

Mandy Chung

> On Apr 20, 2017, at 9:55 AM, Alan Bateman <[hidden email]> wrote:
>
> On 20/04/2017 17:47, Mandy Chung wrote:
>
>> In this case, which module should jdwp-protocol.html spec belong to?  Not jdk.jdwp.agent then.
>> The suggestion of the modular specs layout in the docs bundle may not apply.
>>
> jdwp-protocol.html is the JDWP protocol so it's implemented by both the debugger and debugee. Typically the debugger sends a command and the debuggee responds with a reply. There are also event messages that the target VM/debuggee sends to the debugger. If there is place for Java SE documentation then it might be best to put it there rather than trying to put it in jdk.jdi or jdk.jdwp.agent.

Agree.

Magnus’s proposed patch to put jdwp-protocol.html in the spec/jdwp directory is fine.

Mandy

Loading...