Request Review: JDK-8181639 Add tool and services information to module summary

[Alan Bateman]

(Moving this review thread to jigsaw-dev as this is module descriptions).

On 07/06/2017 06:49, Mandy Chung wrote:
> http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8181639/webrev.00
>
> Updated javadoc:
>     http://cr.openjdk.java.net/~mchung/jdk9/webrevs/8181639/api/
>
> This patch mainly adds @uses, @provides and description of providers and tools.  This uses description list “dl” to list “Providers”, “Specifications”, “Tool Guides” in JDK 9. In the future this can be converted to custom taglets.
>
I agree a taglet would be useful here, especially as the style specified 
to the "dl" tag is copied to many places.

One question for Jon on javadoc: Should the Uses and Provides in the 
javadoc print the fully qualified name rather than the simple name? I 
found myself several times needing to click on the simple name to see 
which area the provider interface is defined in.

I went through all of the updates and have a number of comments/suggestions:

jdk.hotspot.agent
- I think this would be a bit easier to read if we replace "that can 
attach" with "to attach".

java.base
- To date, we've used "jrt file system provider" rather than "JRT 
FileSystem provider" and it should be good to keep that consistent.
- The URI should be "jrt:/" rather than "jrt".
- What would you think about "to enumerate" rather than "than can 
enumerate".
- "can be loaded" -> "can be created".

java.desktop
- I'm in two minds so to whether the @provides should be documented in 
this module. This is a case where the docs should make it clear that the 
java.desktop includes built-in implementations and list the image and 
sound formats that are supported.

java.rmi
- What would you think about trimming this down to:
"The JDK implementation of this module includes the rmiregistry tool to 
start a remote object registry, and the rmid tool to start the 
activation system daemon". (I've switched the order too because rmid is 
less interesting to know about).

java.scripting
- There's a spurious "*" in the description
- Typo "language" -> "languages".

jdk.jartool
- The sentence starting "Instances are ..." follows from the previous 
sentence so I think the paragraph break should be removed.
- The statement that jarsigner does not provide an API is confusing as 
the module exports two APIs for JAR signing. I think you mean the 
ToolProvider and maybe it would be simpler to just drop the sentence.

jdk.jlink
- it might be simpler to list the tools at the start so that it reads:
"Defines the jlink tool for creating run-time images, the jmod tool for 
creating and manipulating JMOD files, and the jimage tool for inspecting 
the JDK-internal container file for classes and resources". This 
ordering then matches the links to the man pages.

jdk.management.agent
- it might be better to say "allows" rather than "enables" as it needs 
configuration to enable.

jdk.zipfs
- "and the ability" - I assume this should be "and provides the ability".
- I think we should remove the reference to 
FileSystemProviders.installedProviders() as that is not the API that 
applications will use to create a zip file system. Instead we can link 
to FileSystems.newFileSystem. I also think we need a table in this 
javadoc to document the "create" and "encoding" properties.

jdk.security.auth
- your update looks fine but we should probably submit a bug to get 
package descriptions added or maybe more text as it's not immediately 
obvious what one can do with this module.

jdk.scripting.nashorn
- the existing module-info.java is inconsistent with the other module 
descriptions. Now might be the opportunity to reformat this.

jdk.scripting.nashorn.shell
- it might be better to say "the command line tool" rather than "a 
command line tool".

I think that is all that I have.

-Alan.