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

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Magnus Ihse Bursie
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

Reply | Threaded
Open this post in threaded view
|

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
>

Reply | Threaded
Open this post in threaded view
|

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

Mandy Chung
In reply to this post by Magnus Ihse Bursie
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 <[hidden email]> 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
>

Reply | Threaded
Open this post in threaded view
|

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

Magnus Ihse Bursie
In reply to this post by Erik Joelsson
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
>>
>

Reply | Threaded
Open this post in threaded view
|

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

Magnus Ihse Bursie
In reply to this post by Mandy Chung

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 <[hidden email]> 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
>>

Reply | Threaded
Open this post in threaded view
|

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
>>> <[hidden email]> 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
>>>
>

Reply | Threaded
Open this post in threaded view
|

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

Mandy Chung
In reply to this post by Magnus Ihse Bursie

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


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

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