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

[Jonathan Gibbons]

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.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
>