Re: Review Request: JDK-8180717: Upgrade the docs bundle index page

[Mandy Chung]

> On May 22, 2017, at 1:02 AM, Magnus Ihse Bursie 
>  wrote:
> 
> On 2017-05-19 22:48, Mandy Chung wrote:
>> This patch updates the build tool to generate an improved presentation of 
>> the module groupings.  A sample page:
>>http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180717/docs/index.html
>> 
>> Webrev:
>>   http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180717/webrev.00/ 
>> 
>> Thanks
>> Mandy
> 
> This does not really affect the build system, so if you want to push this, go 
> ahead. However, I do have some opinions:
> 
> 1) You are re-adding a lot of css rules. This will make it harder to align 
> this page with an common overall look-and-feel using the shared css file.
> 

We should share the common overall L when it makes sense.  With this new 
presentation this may be better to keep the local css rules unless they are 
applicable to other documents.  This page will likely be tweaked and improved 
or redesigned by UE experts in the future.

> 2) I don't want to sound harsh, but, but is this really an improvement? I 
> find this page almost as bad as the old "brick wall". :-( It's 
> incomprehensible until you read the small print legend at the bottom.
> 
> Also, one of the first things I learned in my human-computer interaction 
> classes was to *never* use color as the single discriminating feature. A 
> large minority of the population is color-blind and cannot tell the 
> difference between e.g. red and green, and it's especielly hard if it's like 
> those low saturation colors that you've picked.

This page gives users an easy entrance to navigate to the appropriate 
documentation/modules.  The categorization into Java SE, JDK, etc is not the 
primary importance to most users of this page and so removing the separate 
columns would simplify the presentation.  Yes color-blind is one known concern. 
 This would need UE experts to help here.  Our primary goal is to replace the 
layer cake with a reasonable top-level page in JDK 9 and hand this to 
appropriate experts/designers to work on it.

Mandy

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: Review Request: JDK-8180717: Upgrade the docs bundle index page

[Magnus Ihse Bursie]

On 2017-05-19 22:48, Mandy Chung wrote:

This patch updates the build tool to generate an improved presentation of the 
module groupings.  A sample page:
http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180717/docs/index.html

Webrev:
   http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8180717/webrev.00/   

Thanks
Mandy


This does not really affect the build system, so if you want to push 
this, go ahead. However, I do have some opinions:


1) You are re-adding a lot of css rules. This will make it harder to 
align this page with an common overall look-and-feel using the shared 
css file.


2) I don't want to sound harsh, but, but is this really an improvement? 
I find this page almost as bad as the old "brick wall". :-( It's 
incomprehensible until you read the small print legend at the bottom.


Also, one of the first things I learned in my human-computer interaction 
classes was to *never* use color as the single discriminating feature. A 
large minority of the population is color-blind and cannot tell the 
difference between e.g. red and green, and it's especielly hard if it's 
like those low saturation colors that you've picked.


/Magnus

Re: RFR: JDK-8180651: Make target to run tests on exploded image

[Magnus Ihse Bursie]

On 2017-05-22 09:33, Erik Joelsson wrote:

Hello,

That works for me.

The drawback is that run-test already has a big set of automatic 
suffixes for different tests to run. By using a prefix, those are more 
easily separated during tab completion.


I agree, prefix is better. Go with your original patch, it's fine.

I still think the "exploded image" sounds weird (somewhat like calling 
source files "uncompiled binaries"), but apparently I'm alone with that 
so I'll just have to learn and live with it. ;-)


/Magnus


On the other hand, this suggestion makes it very clear what is being 
asked for, which is good.


/Erik


On 2017-05-20 02:25, Jonathan Gibbons wrote:
"exploded" as an adjective applies well enough to "image" but not to 
the imperative "run-test".


At the risk of a long name, can you move exploded to the end, with 
something like

run-test-exploded-image

-- Jon

On 05/19/2017 08:36 AM, Robbin Ehn wrote:

Hi,

On 05/19/2017 12:55 PM, Erik Joelsson wrote:

Sure we can pause this. Robbin has a local patch to play with for now.


Yes, no rush for me.



If you want another name, then we should also rename 
exploded-image. As I understand it, the name exploded is well 
established. It refers to the java class files/resources not being 
in jars/jimage format, but exploded as separate files in a 
directory structure.


I would prefer to keep the name exploded for these reasons.

/Robbin



/Erik


On 2017-05-19 11:45, Magnus Ihse Bursie wrote:
I like the idea, the changes in itself look good, but I really 
*really* do not like the name "exploded". It was not good before 
as in "exploded-image", but this is even worse. :-(


Can we pause this one for just a while and try really hard to come 
up with a better name? If we fail to do that in a couple of days, 
I'll admit defeat and accept the patch as it is. OK?


What about "local" image? "simple"? "quick"? "bare"?

/Magnus

On 2017-05-19 11:26, Erik Joelsson wrote:
In most cases, when running regression tests, you want to run 
them on the jdk image because that's the correct image and some 
tests will not work on other variants. However, many tests can be 
run successfully on the exploded image and since building the 
full jdk image takes quite a bit of extra time, especially when 
running a slowdebug build, enabling this as an option can 
significantly improve developer efficiency.


I therefor propose the new target "exploded-run-test". It will 
work just like run-test but it depends on and runs on the 
exploded image.


Bug: https://bugs.openjdk.java.net/browse/JDK-8180651

Webrev: http://cr.openjdk.java.net/~erikj/8180651/webrev.01/

/Erik

Re: RFR: JDK-8180480 Use "requires transitive" relationship when determining modules for javadoc

[Magnus Ihse Bursie]

On 2017-05-19 16:47, Mandy Chung wrote:

On May 19, 2017, at 1:08 AM, Magnus Ihse Bursie  
wrote:


"Indirect exports" was a good term. I dropped the "Deps" part of the name and 
it all became much clearer.

Here's an updated webrev:
http://cr.openjdk.java.net/~ihse/JDK-8180480-docs-should-use-requires-transitive/webrev.02


+  $1_INDIRECT_EXPORTS := $$(call FindTransitiveIndirectExportsForModules, 
$$($1_MODULES))

Nit: “exported” term is for API but not for dependency.

s/$1_INDIRECT_EXPORTS/$1_TRANSITIVE_MODULES
s/FindTransitiveIndirectExportsForModules/FindTransitiveIndirectDepsForModules

Otherwise, looks good.  No need for a new webrev:


Well, but that's not really just a "nit", is it? The problem here was 
that "transitive deps" had been used in the names of our macros in a 
different way than "requires transitive" from module-info.java implies, 
and now we're just back in that confusion anyway.


Oh well. I'll settle for those names (but under some protest!) for jdk 
9, and then we'll have to make sure we get a better naming scheme that 
aligns all the way for jdk 10.


/Magnus



Mandy

Re: RFR: JDK-8180651: Make target to run tests on exploded image

[Erik Joelsson]

Hello,

That works for me.

The drawback is that run-test already has a big set of automatic 
suffixes for different tests to run. By using a prefix, those are more 
easily separated during tab completion. On the other hand, this 
suggestion makes it very clear what is being asked for, which is good.


/Erik


On 2017-05-20 02:25, Jonathan Gibbons wrote:
"exploded" as an adjective applies well enough to "image" but not to 
the imperative "run-test".


At the risk of a long name, can you move exploded to the end, with 
something like

run-test-exploded-image

-- Jon

On 05/19/2017 08:36 AM, Robbin Ehn wrote:

Hi,

On 05/19/2017 12:55 PM, Erik Joelsson wrote:

Sure we can pause this. Robbin has a local patch to play with for now.


Yes, no rush for me.



If you want another name, then we should also rename exploded-image. 
As I understand it, the name exploded is well established. It refers 
to the java class files/resources not being in jars/jimage format, 
but exploded as separate files in a directory structure.


I would prefer to keep the name exploded for these reasons.

/Robbin



/Erik


On 2017-05-19 11:45, Magnus Ihse Bursie wrote:
I like the idea, the changes in itself look good, but I really 
*really* do not like the name "exploded". It was not good before as 
in "exploded-image", but this is even worse. :-(


Can we pause this one for just a while and try really hard to come 
up with a better name? If we fail to do that in a couple of days, 
I'll admit defeat and accept the patch as it is. OK?


What about "local" image? "simple"? "quick"? "bare"?

/Magnus

On 2017-05-19 11:26, Erik Joelsson wrote:
In most cases, when running regression tests, you want to run them 
on the jdk image because that's the correct image and some tests 
will not work on other variants. However, many tests can be run 
successfully on the exploded image and since building the full jdk 
image takes quite a bit of extra time, especially when running a 
slowdebug build, enabling this as an option can significantly 
improve developer efficiency.


I therefor propose the new target "exploded-run-test". It will 
work just like run-test but it depends on and runs on the exploded 
image.


Bug: https://bugs.openjdk.java.net/browse/JDK-8180651

Webrev: http://cr.openjdk.java.net/~erikj/8180651/webrev.01/

/Erik