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

[Magnus Ihse Bursie]

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