RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used

[Jonathan Gibbons]

On Thu, 10 Feb 2022 11:24:23 GMT, Lance Andersen <lancea at openjdk.org> wrote:

>> Perhaps like this?
>> 
>> 
>> /**
>>  * ...
>>  * @provides java.util.spi.ToolProvider
>>  *         Module {@code jdk.jartool} provides a tool named {@code "jar"}.
>>  *         Invoke {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst("jar")}
>>  *         to create an instance of this tool.
>>  * ...
>>  */
>
>> Perhaps like this?
>> 
>> ```java
>> /**
>>  * ...
>>  * @provides java.util.spi.ToolProvider
>>  *         Module {@code jdk.jartool} provides a tool named {@code "jar"}.
>>  *         Invoke {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst("jar")}
>>  *         to create an instance of this tool.
>>  * ...
>>  */
>> ```
> 
> What about
> 
> `Module {@code jdk.jartool) provides the equivalent of command-line access to the {@code "jar"} tool`

The focus should be to document the service specified in the `@provides` directive, and how to access to access an instance of the service.

How about:

Use `TP.findFirst("NAME")` to obtain an instance of a `ToolProvider` that provides the equivalent of command-line access to the {@code "NAME"} tool.

-------------

PR: https://git.openjdk.java.net/jdk/pull/7406