RFR: JDK-8172312 Update docs target and image for new combined docs (original) (raw)

Jonathan Gibbons jonathan.gibbons at oracle.com
Tue Apr 4 19:28:18 UTC 2017

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

More information about the build-dev mailing list