Re: RFR: JDK-8175824 Adapt javadoc generation to different requirements for JDK and JavaSE

[Mandy Chung]

> On May 22, 2017, at 1:31 AM, Magnus Ihse Bursie 
>  wrote:
> 
> Updated version:
> 
> http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.02


 207   This is a list of all modules included in the $$($1_FULL_NAME) 
API Specification. \

I suggest to keep the original sentence:

  "This document is the API specification for $$($1_FULL_NAME)."

Otherwise looks good.

Do you have a generated page to check out?

Mandy

Re: RFR: JDK-8175824 Adapt javadoc generation to different requirements for JDK and JavaSE

[Erik Joelsson]

Looks good to me.

/Erik


On 2017-05-22 10:31, Magnus Ihse Bursie wrote:


On 2017-05-19 17:09, Mandy Chung wrote:

Magnus,

Iris and Kevin provides the description for each group.  The overview 
page

can look like this:

This document is the Java™ Platform, Standard Edition Development Kit 
(JDK™) 9  API Specification.


Java SE
 The Java Platform, Standard Edition (“Java SE”) APIs define
the core Java platform for general-purpose computing. These APIs
are in modules with names starting with the string “java.”.

JDK
The Java Development Kit (“JDK”) APIs define an implementation
of the Java SE Platform which may include platform-specific details.
These APIs are in modules with names starting with the string 
“jdk.”.


JavaFX
The JavaFX APIs define a set of user interface (UI) controls,
graphics, media, and web packages for developing rich client
applications. These APIs are in modules with names starting with
the string "javafx.”.

Java SE, JDK, JavaFX links to the corresponding table.


Updated version:

http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.02 



/Magnus


Mandy

On May 19, 2017, at 2:28 AM, Magnus Ihse Bursie 
 wrote:


javadoc allows a file to be specified to provide content for the top 
level "overview" page.


As we move towards a unified docs bundle, we need to be able to vary 
the content of that file depending on the content of the bundle. 
This does not mean providing or including lists of modules, but 
should reflect whether the bundle contains Java SE modules, JDK 
modules and JavaFX modules.


This patch also includes support for (and relies on) the new usage 
of the -group option from JDK-8180336.


Note that when JDK-8180480 (Use "requires transitive" relationship 
when determining modules for javadoc) is pushed, the call to 
FindTransitiveDepsForModules for JavaSE_MODULES should be updated to 
the new FindTransitiveIndirectExportsForModules (or whatever it'll 
end up being called). I'll fix that in whichever of the two bugs I 
push last.


This patch also contains some accumulated cleanup in Docs.gmk after 
all the piecemeal patches this file has recieved for the last few 
weeks.


Note: While I'm willing to make minor changes to the actual contents 
of the generated overview.html, I'd prefer if any larger (or 
potentially controversial) issues are handled as separate follow-up 
bugs. With this framework in place, it's easy to modify whatever 
gets written to the file.


An example how this looks like for the JDK and Java SE documentation 
collections (stripped down to the summary page of the javadoc 
output, and the JDK top-level index.html) is here:

http://cr.openjdk.java.net/~ihse/demo-generated-overview/

Bug: https://bugs.openjdk.java.net/browse/JDK-8175824
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.01

Re: RFR: JDK-8175824 Adapt javadoc generation to different requirements for JDK and JavaSE

[Magnus Ihse Bursie]

On 2017-05-19 17:09, Mandy Chung wrote:

Magnus,

Iris and Kevin provides the description for each group.  The overview page
can look like this:

This document is the Java™ Platform, Standard Edition Development Kit (JDK™) 9  
API Specification.

Java SE
 The Java Platform, Standard Edition (“Java SE”) APIs define
the core Java platform for general-purpose computing. These APIs
are in modules with names starting with the string “java.”.

JDK
The Java Development Kit (“JDK”) APIs define an implementation
of the Java SE Platform which may include platform-specific details.
These APIs are in modules with names starting with the string “jdk.”.

JavaFX
The JavaFX APIs define a set of user interface (UI) controls,
graphics, media, and web packages for developing rich client
applications. These APIs are in modules with names starting with
the string "javafx.”.

Java SE, JDK, JavaFX links to the corresponding table.


Updated version:

http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.02

/Magnus


Mandy


On May 19, 2017, at 2:28 AM, Magnus Ihse Bursie  
wrote:

javadoc allows a file to be specified to provide content for the top level 
"overview" page.

As we move towards a unified docs bundle, we need to be able to vary the 
content of that file depending on the content of the bundle. This does not mean 
providing or including lists of modules, but should reflect whether the bundle 
contains Java SE modules, JDK modules and JavaFX modules.

This patch also includes support for (and relies on) the new usage of the 
-group option from JDK-8180336.

Note that when JDK-8180480 (Use "requires transitive" relationship when 
determining modules for javadoc) is pushed, the call to FindTransitiveDepsForModules for 
JavaSE_MODULES should be updated to the new FindTransitiveIndirectExportsForModules (or 
whatever it'll end up being called). I'll fix that in whichever of the two bugs I push 
last.

This patch also contains some accumulated cleanup in Docs.gmk after all the 
piecemeal patches this file has recieved for the last few weeks.

Note: While I'm willing to make minor changes to the actual contents of the 
generated overview.html, I'd prefer if any larger (or potentially 
controversial) issues are handled as separate follow-up bugs. With this 
framework in place, it's easy to modify whatever gets written to the file.

An example how this looks like for the JDK and Java SE documentation 
collections (stripped down to the summary page of the javadoc output, and the 
JDK top-level index.html) is here:
http://cr.openjdk.java.net/~ihse/demo-generated-overview/

Bug: https://bugs.openjdk.java.net/browse/JDK-8175824
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.01

Re: RFR: JDK-8175824 Adapt javadoc generation to different requirements for JDK and JavaSE

[Magnus Ihse Bursie]

On 2017-05-19 13:10, Erik Joelsson wrote:

Looks good.

Minor nit. There are variables named JavaSE_MODULES as well as 
JAVASE_MODULES which can be a bit confusing. Perhaps the latter can be 
inlined at this point? Or the first should perhaps be called 
JavaSE_GROUP_MODULES?

I agree, that was confusing. I inlined it instead.

/Magnus



/Erik


On 2017-05-19 11:28, Magnus Ihse Bursie wrote:
javadoc allows a file to be specified to provide content for the top 
level "overview" page.


As we move towards a unified docs bundle, we need to be able to vary 
the content of that file depending on the content of the bundle. This 
does not mean providing or including lists of modules, but should 
reflect whether the bundle contains Java SE modules, JDK modules and 
JavaFX modules.


This patch also includes support for (and relies on) the new usage of 
the -group option from JDK-8180336.


Note that when JDK-8180480 (Use "requires transitive" relationship 
when determining modules for javadoc) is pushed, the call to 
FindTransitiveDepsForModules for JavaSE_MODULES should be updated to 
the new FindTransitiveIndirectExportsForModules (or whatever it'll 
end up being called). I'll fix that in whichever of the two bugs I 
push last.


This patch also contains some accumulated cleanup in Docs.gmk after 
all the piecemeal patches this file has recieved for the last few weeks.


Note: While I'm willing to make minor changes to the actual contents 
of the generated overview.html, I'd prefer if any larger (or 
potentially controversial) issues are handled as separate follow-up 
bugs. With this framework in place, it's easy to modify whatever gets 
written to the file.


An example how this looks like for the JDK and Java SE documentation 
collections (stripped down to the summary page of the javadoc output, 
and the JDK top-level index.html) is here:

http://cr.openjdk.java.net/~ihse/demo-generated-overview/

Bug: https://bugs.openjdk.java.net/browse/JDK-8175824
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.01

Re: RFR: JDK-8175824 Adapt javadoc generation to different requirements for JDK and JavaSE

[Mandy Chung]

Magnus,

Iris and Kevin provides the description for each group.  The overview page
can look like this:

This document is the Java™ Platform, Standard Edition Development Kit (JDK™) 9  
API Specification.

Java SE
The Java Platform, Standard Edition (“Java SE”) APIs define 
the core Java platform for general-purpose computing. These APIs
are in modules with names starting with the string “java.”.

JDK
The Java Development Kit (“JDK”) APIs define an implementation
of the Java SE Platform which may include platform-specific details. 
These APIs are in modules with names starting with the string “jdk.”.

JavaFX
The JavaFX APIs define a set of user interface (UI) controls,
graphics, media, and web packages for developing rich client 
applications. These APIs are in modules with names starting with 
the string "javafx.”.

Java SE, JDK, JavaFX links to the corresponding table.

Mandy

> On May 19, 2017, at 2:28 AM, Magnus Ihse Bursie 
>  wrote:
> 
> javadoc allows a file to be specified to provide content for the top level 
> "overview" page.
> 
> As we move towards a unified docs bundle, we need to be able to vary the 
> content of that file depending on the content of the bundle. This does not 
> mean providing or including lists of modules, but should reflect whether the 
> bundle contains Java SE modules, JDK modules and JavaFX modules.
> 
> This patch also includes support for (and relies on) the new usage of the 
> -group option from JDK-8180336.
> 
> Note that when JDK-8180480 (Use "requires transitive" relationship when 
> determining modules for javadoc) is pushed, the call to 
> FindTransitiveDepsForModules for JavaSE_MODULES should be updated to the new 
> FindTransitiveIndirectExportsForModules (or whatever it'll end up being 
> called). I'll fix that in whichever of the two bugs I push last.
> 
> This patch also contains some accumulated cleanup in Docs.gmk after all the 
> piecemeal patches this file has recieved for the last few weeks.
> 
> Note: While I'm willing to make minor changes to the actual contents of the 
> generated overview.html, I'd prefer if any larger (or potentially 
> controversial) issues are handled as separate follow-up bugs. With this 
> framework in place, it's easy to modify whatever gets written to the file.
> 
> An example how this looks like for the JDK and Java SE documentation 
> collections (stripped down to the summary page of the javadoc output, and the 
> JDK top-level index.html) is here:
> http://cr.openjdk.java.net/~ihse/demo-generated-overview/
> 
> Bug: https://bugs.openjdk.java.net/browse/JDK-8175824
> WebRev: 
> http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.01
> 

Re: RFR: JDK-8175824 Adapt javadoc generation to different requirements for JDK and JavaSE

[Erik Joelsson]

Looks good.

Minor nit. There are variables named JavaSE_MODULES as well as 
JAVASE_MODULES which can be a bit confusing. Perhaps the latter can be 
inlined at this point? Or the first should perhaps be called 
JavaSE_GROUP_MODULES?


/Erik


On 2017-05-19 11:28, Magnus Ihse Bursie wrote:
javadoc allows a file to be specified to provide content for the top 
level "overview" page.


As we move towards a unified docs bundle, we need to be able to vary 
the content of that file depending on the content of the bundle. This 
does not mean providing or including lists of modules, but should 
reflect whether the bundle contains Java SE modules, JDK modules and 
JavaFX modules.


This patch also includes support for (and relies on) the new usage of 
the -group option from JDK-8180336.


Note that when JDK-8180480 (Use "requires transitive" relationship 
when determining modules for javadoc) is pushed, the call to 
FindTransitiveDepsForModules for JavaSE_MODULES should be updated to 
the new FindTransitiveIndirectExportsForModules (or whatever it'll end 
up being called). I'll fix that in whichever of the two bugs I push last.


This patch also contains some accumulated cleanup in Docs.gmk after 
all the piecemeal patches this file has recieved for the last few weeks.


Note: While I'm willing to make minor changes to the actual contents 
of the generated overview.html, I'd prefer if any larger (or 
potentially controversial) issues are handled as separate follow-up 
bugs. With this framework in place, it's easy to modify whatever gets 
written to the file.


An example how this looks like for the JDK and Java SE documentation 
collections (stripped down to the summary page of the javadoc output, 
and the JDK top-level index.html) is here:

http://cr.openjdk.java.net/~ihse/demo-generated-overview/

Bug: https://bugs.openjdk.java.net/browse/JDK-8175824
WebRev: 
http://cr.openjdk.java.net/~ihse/JDK-8175824-javadoc-dynamic-overview-and-groups/webrev.01