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.reinh...@oracle.com wrote:
2017/3/30 6:05:43 -0700, magnus.ihse.bur...@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
