RFR: JDK-8172312 Update docs target and image for new combined docs (original) (raw)

Magnus Ihse Bursie magnus.ihse.bursie at oracle.com
Mon Apr 3 10:24:52 UTC 2017

Mark,

I think the distinction you ask for is already there. The two separate make targets "docs-javadoc" and "docs-reference" builds two distinct images "docs" and "javase-docs", respectively. The first of these builds the complete Java SE + JDK documentation, the second build just the Java SE documentation.

I do not think it's a good idea to go further and actually remove the Java SE part from the complete "docs" image. Upholding such a formal difference between different parts of the JDK is likely to be just confusing to common Java developers. I believe that enforcing such a cut would eliminate much of the work that has been put into giving the the Java developer community a unified access to all releveant documentation.

With that said, we should change the heading so that only the javase-docs image claims to be the SE specification. (Note that this incorrect claim is not a regression, since this is what the core-docs api has been saying since long time ago, even while containing Oracle-specific classes...)

/Magnus

On 2017-04-01 20:25, mark.reinhold at oracle.com wrote:

2017/3/30 6:05:43 -0700, magnus.ihse.bursie at oracle.com:

As a part of JEP 299, we should build the Javadoc as a single combined output, instead of a dozen or so individual javadoc bundles. This bug fixes this. The selection on what to include is now based on modules instead of packages. I'm worried that perhaps we've unified a bit too much here. This patch does build all the Javadoc together, as advertised, but that places the jdk.* modules together with the java.* modules under the heading "Java Platform, Standard Edition 9 API Specification", and of course the jdk.* modules aren't part of that spec. JDK 9 is the "Reference Implementation" (in JCP terms) of Java SE 9, so it's important to keep a clear distinction between the SE-standard parts of the spec and those that are JDK-specific. Would it make sense instead to have docs/api be just for the SE (i.e., java.*) modules, and then place the Javadoc for the jdk.* modules under docs/api/jdk? There could be a helpful link from the SE API title page to the JDK API title page, but it should make it clear that the JDK APIs aren't part of the SE spec. - Mark

More information about the build-dev mailing list