Mark,
I agree there will need to be some cosmetic cleanup with respect to
headings. Given the optionality of whether or not the build is set to
import JavaFX, the headings and content of the new overview page will
need to be somewhat synthesized.
Separately, it has always been a requirement to support the generation
of "Java SE"-only docs, which can be produced independently of the
consolidated docs.
The advantage of being able to generate a single big bundle is that the
new "javadoc Search" feature will work as expected. If we partition the
docs, then the scope of any search will be restricted to the subset of
docs currently being viewed.
-- Jon
On 04/03/2017 03:24 AM, Magnus Ihse Bursie wrote:
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
