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

[Mandy Chung]

> On Apr 20, 2017, at 12:21 AM, Magnus Ihse Bursie <magnus.ihse.bursie at oracle.com> 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