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

[Magnus Ihse Bursie]

On 2017-04-04 21:28, Jonathan Gibbons wrote:
> Magnus, Mark,
>
> Don't we need the JEP to be moved from "Proposed To Target" to 
> "Targetted" before we can push?
I would have assumed that since the patch itself has been code reviewed, 
and follows the "noreg-doc" rule, it would be fair game to push, 
regardless of it's relation to a JEP (that covers many other 
documentation issues). But then again, I'm no expert in these procedural 
questions.

/Magnus

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