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

Tue, 04 Apr 2017 13:31:40 -0700 


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.reinh...@oracle.com wrote:

2017/4/3 3:24:52 -0700, magnus.ihse.bur...@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

Reply via email to