Looks good to me.
/Erik
On 2017-04-04 13:47, 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
