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

[Christian Stein]

On Thu, 10 Feb 2022 17:24:17 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>>> 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.

I think Jon's latest proposal combines all requirements with using better wording than my initial text.

Do you agree, @AlanBateman and @LanceAndersen?

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

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