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

[Jonathan Gibbons]

Magnus, Mark,

Don't we need the JEP to be moved from "Proposed To Target" to 
"Targetted" before we can push?

-- Jon

On 04/04/2017 04:47 AM, Magnus Ihse Bursie wrote:
> Here is an updated webrev:
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.03
>
> The only change compared to the previous webrev is that I have updated 
> the title for the JDK javadocs so it does not claim to be Java SE.
>
> I have filed the following follow-up bugs to address Mark's concerns, 
> and concerns expressed elsewhere:
>
> * JDK-8178043 Group Java SE, JDK and JavaFX modules in unified javadoc 
> [1]
> * JDK-8178037 Move information from jdi-overview.html into jdk.jdi 
> module-info.java [2]
> * JDK-8178038 Copy jdwp-protocol.html to proper location [3]
> * JDK-8178039 Copy jvmti.html to proper location [4]
>
> I hope JDK-8178043 captures the intent of the solution I understand 
> that Mark and Jon seemed to agree upon.
>
> I also refer to the previously existing:
>
> * JDK-8175824 Provide more flexible means for setting the overview 
> text in the generated docs [5]
>
> which I have amended with the task of also making sure that the values 
> of the title text snippets gets proper values.
>
> Since a lot of the continued work on Javadoc changes in JDK 9 is 
> dependent on this change, I hope it is now clear for pushing.
>
> /Magnus
>
> [1] https://bugs.openjdk.java.net/browse/JDK-8178043
> [2] https://bugs.openjdk.java.net/browse/JDK-8178037
> [3] https://bugs.openjdk.java.net/browse/JDK-8178038
> [4] https://bugs.openjdk.java.net/browse/JDK-8178039
> [5] https://bugs.openjdk.java.net/browse/JDK-8175824
>
>
> On 2017-04-04 01:38, mark.reinhold at oracle.com wrote:
>> 2017/4/3 3:24:52 -0700, magnus.ihse.bursie at oracle.com:
>>> 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'm glad that there's an SE-only target, but that's not what I asked
>> for.
>>
>>> I do not think it's a good idea to go further and actually *remove* the
>>> Java SE part from the complete "docs" image.
>> That's not what I asked for, either.  I suggested making a stronger
>> distinction between the specifications of the SE APIs and those of the
>> rest of the JDK, by putting the latter in a subdirectory of the same
>> image.  Sorry if that wasn't clear.
>>
>>> 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.
>> I see your point, but failing to make a strong distinction could also
>> confuse developers, since it may lead some to use JDK-specific APIs when
>> they really want to write code that's portable to any SE implementation.
>>
>> Still, there may be better ways to make that distinction, as Jon 
>> suggests
>> nearby.
>>
>>> With that said, we should change the heading so that only the
>>> javase-docs image claims to be the SE specification.
>> Yes, we must do that, at a bare minimum.
>>
>> - Mark
>