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

[mark . reinhold]

2017/4/4 12:28:18 -0700, jonathan.gibb...@oracle.com:
> Don't we need the JEP to be moved from "Proposed To Target" to 
> "Targetted" before we can push?

Yep.  Coming right up ...

- Mark

Re: 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.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

Re: 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.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

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

[mark . reinhold]

2017/4/4 4:47:58 -0700, magnus.ihse.bur...@oracle.com:
> 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.

Yes, I think it does.  Thanks for filing it.

- Mark

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

[Erik Joelsson]

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

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

[Magnus Ihse Bursie]

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

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

[Jonathan Gibbons]

On 04/03/2017 04:42 PM, mark.reinh...@oracle.com wrote:

2017/4/3 11:01:13 -0700, jonathan.gibb...@oracle.com:

I agree there will need to be some cosmetic cleanup with respect to
headings. Given the optionality of whether or not the build is set to
import JavaFX, the headings and content of the new overview page will
need to be somewhat synthesized.

Is it possible to have (up to) three sections of modules on the front
page, where the first is headed by an orange "Java SE Modules" box, the
second is "JavaFX Modules", and the third is "JDK Modules"?

That, plus an updated title and some prose to explain that the first
section is standard and the rest are not, would probably do the trick.


I'm not sure that we can partition the modules table in the remaining 
time for 9,

although I do like the suggestion.

My thought had been to focus on the prose, so that the introductory text 
on the

page has 3 paragraphs with appropriate subheadings, for the 3 groups that
you mention.  I was hoping that the makefiles would then be able to 
determine

which of those 3 sections would be appropriate for the docs bundle being
generated.

Going forward, I was thinking to repurpose the under-used -group option
to give something like the visual grouping you suggest.

See:
http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#group

Using the existing technology, it might be reasonably easy to change the
existing table, so that the Modules tab can replaced by a series of tabs
labelled  "All Modules", "Java SE Modules", "JavaFX Modules" and "JDK 
Modules".


I can raise this with the rest of jaavdoc team to see how difficult that 
would be

in the remaining time.





The advantage of being able to generate a single big bundle is that the
new "javadoc Search" feature will work as expected.  If we partition the
docs, then the scope of any search will be restricted to the subset of
docs currently being viewed.

I agree that a unified search experience is very useful.

- Mark

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

[mark . reinhold]

2017/4/3 11:01:13 -0700, jonathan.gibb...@oracle.com:
> I agree there will need to be some cosmetic cleanup with respect to 
> headings. Given the optionality of whether or not the build is set to 
> import JavaFX, the headings and content of the new overview page will 
> need to be somewhat synthesized.

Is it possible to have (up to) three sections of modules on the front
page, where the first is headed by an orange "Java SE Modules" box, the
second is "JavaFX Modules", and the third is "JDK Modules"?

That, plus an updated title and some prose to explain that the first
section is standard and the rest are not, would probably do the trick.

> The advantage of being able to generate a single big bundle is that the 
> new "javadoc Search" feature will work as expected.  If we partition the 
> docs, then the scope of any search will be restricted to the subset of 
> docs currently being viewed.

I agree that a unified search experience is very useful.

- Mark

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

[mark . reinhold]

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

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

[Jonathan Gibbons]

Mark,

I agree there will need to be some cosmetic cleanup with respect to 
headings. Given the optionality of whether or not the build is set to 
import JavaFX, the headings and content of the new overview page will 
need to be somewhat synthesized.


Separately, it has always been a requirement to support the generation 
of "Java SE"-only docs, which can be produced independently of the 
consolidated docs.


The advantage of being able to generate a single big bundle is that the 
new "javadoc Search" feature will work as expected.  If we partition the 
docs, then the scope of any search will be restricted to the subset of 
docs currently being viewed.


-- Jon

On 04/03/2017 03:24 AM, Magnus Ihse Bursie wrote:

Mark,

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 do not think it's a good idea to go further and actually *remove* 
the Java SE part from the complete "docs" image. 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.


With that said, we should change the heading so that only the 
javase-docs image claims to be the SE specification. (Note that this 
incorrect claim is not a regression, since this is what the core-docs 
api has been saying since long time ago, even while containing 
Oracle-specific classes...)


/Magnus

On 2017-04-01 20:25, mark.reinh...@oracle.com wrote:

2017/3/30 6:05:43 -0700, magnus.ihse.bur...@oracle.com:

As a part of JEP 299, we should build the Javadoc as a single combined
output, instead of a dozen or so individual javadoc bundles. This bug
fixes this. The selection on what to include is now based on modules
instead of packages.

I'm worried that perhaps we've unified a bit too much here.

This patch does build all the Javadoc together, as advertised, but that
places the `jdk.*` modules together with the `java.*` modules under the
heading "Java Platform, Standard Edition 9 API Specification", and of
course the `jdk.*` modules aren't part of that spec.

JDK 9 is the "Reference Implementation" (in JCP terms) of Java SE 9, so
it's important to keep a clear distinction between the SE-standard parts
of the spec and those that are JDK-specific.

Would it make sense instead to have `docs/api` be just for the SE (i.e.,
`java.*`) modules, and then place the Javadoc for the `jdk.*` modules
under `docs/api/jdk`?  There could be a helpful link from the SE API
title page to the JDK API title page, but it should make it clear that
the JDK APIs aren't part of the SE spec.

- Mark

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

[Magnus Ihse Bursie]

Mark,

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 do not think it's a good idea to go further and actually *remove* the 
Java SE part from the complete "docs" image. 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.


With that said, we should change the heading so that only the 
javase-docs image claims to be the SE specification. (Note that this 
incorrect claim is not a regression, since this is what the core-docs 
api has been saying since long time ago, even while containing 
Oracle-specific classes...)


/Magnus

On 2017-04-01 20:25, mark.reinh...@oracle.com wrote:

2017/3/30 6:05:43 -0700, magnus.ihse.bur...@oracle.com:

As a part of JEP 299, we should build the Javadoc as a single combined
output, instead of a dozen or so individual javadoc bundles. This bug
fixes this. The selection on what to include is now based on modules
instead of packages.

I'm worried that perhaps we've unified a bit too much here.

This patch does build all the Javadoc together, as advertised, but that
places the `jdk.*` modules together with the `java.*` modules under the
heading "Java Platform, Standard Edition 9 API Specification", and of
course the `jdk.*` modules aren't part of that spec.

JDK 9 is the "Reference Implementation" (in JCP terms) of Java SE 9, so
it's important to keep a clear distinction between the SE-standard parts
of the spec and those that are JDK-specific.

Would it make sense instead to have `docs/api` be just for the SE (i.e.,
`java.*`) modules, and then place the Javadoc for the `jdk.*` modules
under `docs/api/jdk`?  There could be a helpful link from the SE API
title page to the JDK API title page, but it should make it clear that
the JDK APIs aren't part of the SE spec.

- Mark

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

[mark . reinhold]

2017/3/30 6:05:43 -0700, magnus.ihse.bur...@oracle.com:
> As a part of JEP 299, we should build the Javadoc as a single combined 
> output, instead of a dozen or so individual javadoc bundles. This bug 
> fixes this. The selection on what to include is now based on modules 
> instead of packages.

I'm worried that perhaps we've unified a bit too much here.

This patch does build all the Javadoc together, as advertised, but that
places the `jdk.*` modules together with the `java.*` modules under the
heading "Java Platform, Standard Edition 9 API Specification", and of
course the `jdk.*` modules aren't part of that spec.

JDK 9 is the "Reference Implementation" (in JCP terms) of Java SE 9, so
it's important to keep a clear distinction between the SE-standard parts
of the spec and those that are JDK-specific.

Would it make sense instead to have `docs/api` be just for the SE (i.e.,
`java.*`) modules, and then place the Javadoc for the `jdk.*` modules
under `docs/api/jdk`?  There could be a helpful link from the SE API
title page to the JDK API title page, but it should make it clear that
the JDK APIs aren't part of the SE spec.

- Mark

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

[Magnus Ihse Bursie]

On 2017-03-31 10:02, Erik Joelsson wrote:

Looks good to me.

My suggestion was to to add the rmic dirs to those variables in 
Javadoc.gmk, but your solution is even better. I didn't realize that 
you could just add to a "pathlist" with another call to PathList, so I 
thought we had to get at the variables that GetModuleSrcPath uses as 
input. 


That's even documented! :-) "Safe for multiple nested calls."

Anyway, very nice to not have to duplicate the list of source dirs 
anymore.


Yep, indeed.

/Magnus



/Erik


On 2017-03-30 22:17, Magnus Ihse Bursie wrote:


On 2017-03-30 21:19, Magnus Ihse Bursie wrote:


New webrev coming up soon... 


Here it is:

http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02

Changes since last webrev:

 * Removed java.base from DOCS_MODULES and updated comment.
 * Removed jdk.crypto.mscapi and jdk.crypto.ucrypto from DOCS_MODULES.
 * Replaced JAVADOC_SOURCE_DIRS with
JAVADOC_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
$(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
   and added it to JAVADOC_VARDEPS
 * Fixed JAVADOC_TOP indentation
 * Removed java.base from list of modules for reference javase javadoc
 * Updated REFERENCE_TARGET_DIR to $(IMAGES_OUTPUTDIR)/javase-docs/api

/Magnus

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

[Erik Joelsson]

Looks good to me.

My suggestion was to to add the rmic dirs to those variables in 
Javadoc.gmk, but your solution is even better. I didn't realize that you 
could just add to a "pathlist" with another call to PathList, so I 
thought we had to get at the variables that GetModuleSrcPath uses as 
input. Anyway, very nice to not have to duplicate the list of source 
dirs anymore.


/Erik


On 2017-03-30 22:17, Magnus Ihse Bursie wrote:


On 2017-03-30 21:19, Magnus Ihse Bursie wrote:


New webrev coming up soon... 


Here it is:

http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02

Changes since last webrev:

 * Removed java.base from DOCS_MODULES and updated comment.
 * Removed jdk.crypto.mscapi and jdk.crypto.ucrypto from DOCS_MODULES.
 * Replaced JAVADOC_SOURCE_DIRS with
JAVADOC_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
$(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
   and added it to JAVADOC_VARDEPS
 * Fixed JAVADOC_TOP indentation
 * Removed java.base from list of modules for reference javase javadoc
 * Updated REFERENCE_TARGET_DIR to $(IMAGES_OUTPUTDIR)/javase-docs/api

/Magnus

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

[Mandy Chung]

> On Mar 30, 2017, at 1:17 PM, Magnus Ihse Bursie 
>  wrote:
> 
> 
> On 2017-03-30 21:19, Magnus Ihse Bursie wrote:
>> 
>> New webrev coming up soon... 
> 
> Here it is:
> 
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02

Looks good to me.

FYI. I created https://bugs.openjdk.java.net/browse/JDK-8177849 for the 
platform-specific modules issue.

Mandy

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

[Magnus Ihse Bursie]

On 2017-03-30 21:19, Magnus Ihse Bursie wrote:


New webrev coming up soon... 


Here it is:

http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.02

Changes since last webrev:

 * Removed java.base from DOCS_MODULES and updated comment.
 * Removed jdk.crypto.mscapi and jdk.crypto.ucrypto from DOCS_MODULES.
 * Replaced JAVADOC_SOURCE_DIRS with
JAVADOC_SOURCE_PATH := $(call PathList, $(call GetModuleSrcPath) \
$(SUPPORT_OUTPUTDIR)/rmic/* $(JDK_TOPDIR)/src/*/share/doc/stub)
   and added it to JAVADOC_VARDEPS
 * Fixed JAVADOC_TOP indentation
 * Removed java.base from list of modules for reference javase javadoc
 * Updated REFERENCE_TARGET_DIR to $(IMAGES_OUTPUTDIR)/javase-docs/api

/Magnus

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

[Magnus Ihse Bursie]

On 2017-03-30 15:42, Erik Joelsson wrote:

Hello,

Javadoc.gmk:159 looks like too much indentation

The variable JAVADOC_SOURCE_DIRS is starting to seem a bit redundant. 
It does contain two directories that would not be included if you 
replaced $(call PathList, $(JAVADOC_SOURCE_DIRS)) with $(call 
GetModuleSrcPath), but that could be rectified by adding 
$(SUPPORT_OUTPUTDIR)/rmic to GENERATED_SRC_DIRS and share/doc/stub to 
SRC_SUBDIRS in Javadoc.gmk. Doing so would make the dependency 
calculation and the actual source dir input be based on the same 
definitions.


This is a really nice idea! Unfortunately, it was not so easy. :-(

Adding rmic to GENERATED_SRC_DIRS causes java.base compilation to fail with:
Compiling 2898 files for java.base
warning: [path] bad path element 
"/localhome/hg/jdk9-sandbox/build/linux-x64/support/rmic": no such directory

error: warnings found and -Werror specified
1 error

I could of course add an mkdir somewhere before java.base-java is 
executed, but it doesn't really feel good. I think it's better to 
explicitly add the rmic gensrc dir to the javadoc generation.


The same goes for the share/doc/stub. Adding it caused a whole bunch of 
errors when compiling java.management.rmi:
/localhome/hg/jdk9-sandbox/jdk/src/java.rmi/share/doc/stub/java/rmi/activation/ActivationGroup_Stub.java:72: 
warning: [rawtypes] found raw type: MarshalledObject

public java.rmi.MarshalledObject newInstance(
   ^
  missing type arguments for generic class MarshalledObject
  where T is a type-variable:
...

I assume that the sole reason for putting ActivationGroup_Stub.java into 
the "share/doc/stub" directory was to prohibit it from being part of 
normal compilation.


So, once more, I'll rather add that directory to just the javadoc 
generation.


Nevertheless, using $(call GetModuleSrcPath) instead is very nice, even 
if I have to add a couple of paths.


New webrev coming up soon...

/Magnus



/Erik

On 2017-03-30 15:05, Magnus Ihse Bursie wrote:
As a part of JEP 299, we should build the Javadoc as a single 
combined output, instead of a dozen or so individual javadoc bundles. 
This bug fixes this. The selection on what to include is now based on 
modules instead of packages.


The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s) 
does not exist, otherwise find can emit an error message. (This was 
provoked by the new call to SetupZipArchive).


The module selection has been contributed by Mandy Chang.

I intend to push this to JDK9. Since this is a noreg-doc bug, no 
special RDP2 process is required.


Bug: https://bugs.openjdk.java.net/browse/JDK-8172312
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01


/Magnus

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

[Mandy Chung]

> On Mar 30, 2017, at 6:05 AM, Magnus Ihse Bursie 
>  wrote:
> 
> As a part of JEP 299, we should build the Javadoc as a single combined 
> output, instead of a dozen or so individual javadoc bundles. This bug fixes 
> this. The selection on what to include is now based on modules instead of 
> packages.
> 
> The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s) does not 
> exist, otherwise find can emit an error message. (This was provoked by the 
> new call to SetupZipArchive).
> 
> The module selection has been contributed by Mandy Chang.
> 
> I intend to push this to JDK9. Since this is a noreg-doc bug, no special RDP2 
> process is required.
> 
> Bug: https://bugs.openjdk.java.net/browse/JDK-8172312 
> 
> WebRev: 
> http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01 
> 


make/common/Modules.gmk

I should have cleaned this up in the sandbox and I will leave it for you if you 
don’t mind.
 141 #
 142 # Workaround --expand-requires transitive that does not include java.base
 143 #
 144 DOCS_MODULES += \
 145 java.base \
https://bugs.openjdk.java.net/browse/JDK-8176481 has been fixed.  This can be 
removed now.  It’d be good to add a comment something like this.

# DOCS_MODULES defines the root modules for javadoc generation.
# All of their `require transitive` modules directly and indirectly will be 
included.

I will file an issue to follow up the platform-specific modules.   Can you 
remove 
 125   DOCS_MODULES += jdk.crypto.mscapi
 130   DOCS_MODULES += jdk.crypto.ucrypto
make/Javadoc.gmk
 224 REFERENCE_TARGET_DIR := $(SUPPORT_OUTPUTDIR)/javase-api
I suggest to name the javadoc output directory as “javase-docs/api” in the same 
layout as described in JEP 299.  It may copy the specs under javase-docs/specs 
directory in the future.
 239 --module $(call CommaList, java.base java.se.ee))
java.base can be removed since JDK-8176481 has been resolved.
Mandy

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

[Erik Joelsson]

Hello,

Javadoc.gmk:159 looks like too much indentation

The variable JAVADOC_SOURCE_DIRS is starting to seem a bit redundant. It 
does contain two directories that would not be included if you replaced 
$(call PathList, $(JAVADOC_SOURCE_DIRS)) with $(call GetModuleSrcPath), 
but that could be rectified by adding $(SUPPORT_OUTPUTDIR)/rmic to 
GENERATED_SRC_DIRS and share/doc/stub to SRC_SUBDIRS in Javadoc.gmk. 
Doing so would make the dependency calculation and the actual source dir 
input be based on the same definitions.


/Erik

On 2017-03-30 15:05, Magnus Ihse Bursie wrote:
As a part of JEP 299, we should build the Javadoc as a single combined 
output, instead of a dozen or so individual javadoc bundles. This bug 
fixes this. The selection on what to include is now based on modules 
instead of packages.


The fix in MakeBase.gmk is to keep CacheFind quiet if the src dir(s) 
does not exist, otherwise find can emit an error message. (This was 
provoked by the new call to SetupZipArchive).


The module selection has been contributed by Mandy Chang.

I intend to push this to JDK9. Since this is a noreg-doc bug, no 
special RDP2 process is required.


Bug: https://bugs.openjdk.java.net/browse/JDK-8172312
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8172312-combined-javadocs/webrev.01


/Magnus