RFR: JDK-8172312 Update docs target and image for new combined docs

[Magnus Ihse Bursie]

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