Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used [v3]
On Tue, 15 Feb 2022 06:40:57 GMT, Christian Stein wrote: >> A number of modules declare that the "provide" ToolProvider. >> >> These modules now specify the "name" of the argument used by >> `ToolProvider.findFirst` to access an instance of the tool provider within >> the description part of a `@provides` API tag. > > Christian Stein has updated the pull request incrementally with one > additional commit since the last revision: > > Fix typo > > [skip actions] Marked as reviewed by alanb (Reviewer). - PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used [v3]
On Tue, 15 Feb 2022 06:40:57 GMT, Christian Stein wrote: >> A number of modules declare that the "provide" ToolProvider. >> >> These modules now specify the "name" of the argument used by >> `ToolProvider.findFirst` to access an instance of the tool provider within >> the description part of a `@provides` API tag. > > Christian Stein has updated the pull request incrementally with one > additional commit since the last revision: > > Fix typo > > [skip actions] I think we are looking good. Thank you for your persistence on the wordsmithing - Marked as reviewed by lancea (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used [v3]
> A number of modules declare that the "provide" ToolProvider. > > These modules now specify the "name" of the argument used by > `ToolProvider.findFirst` to access an instance of the tool provider within > the description part of a `@provides` API tag. Christian Stein has updated the pull request incrementally with one additional commit since the last revision: Fix typo [skip actions] - Changes: - all: https://git.openjdk.java.net/jdk/pull/7406/files - new: https://git.openjdk.java.net/jdk/pull/7406/files/eaa9a322..ca92a6cc Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7406&range=02 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7406&range=01-02 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/7406.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/7406/head:pull/7406 PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used [v2]
> A number of modules declare that the "provide" ToolProvider. > > These modules now specify the "name" of the argument used by > `ToolProvider.findFirst` to access an instance of the tool provider within > the description part of a `@provides` API tag. Christian Stein has updated the pull request incrementally with one additional commit since the last revision: Update wording - Changes: - all: https://git.openjdk.java.net/jdk/pull/7406/files - new: https://git.openjdk.java.net/jdk/pull/7406/files/56e0c249..eaa9a322 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=7406&range=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=7406&range=00-01 Stats: 19 lines in 6 files changed: 1 ins; 0 del; 18 mod Patch: https://git.openjdk.java.net/jdk/pull/7406.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/7406/head:pull/7406 PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Mon, 14 Feb 2022 18:20:19 GMT, Christian Stein wrote: > I think Jon's latest proposal combines all requirements with using better > wording than my initial text. > > Do you agree, @AlanBateman and @LanceAndersen? Yes, I think that sounds good - PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Thu, 10 Feb 2022 17:24:17 GMT, Jonathan Gibbons 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
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Thu, 10 Feb 2022 11:24:23 GMT, Lance Andersen 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
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Thu, 10 Feb 2022 03:04:43 GMT, Christian Stein wrote:
>> What is "it" in "it provides..." ?
>
> 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`
-
PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Thu, 10 Feb 2022 02:19:36 GMT, Jonathan Gibbons wrote:
>> src/jdk.jartool/share/classes/module-info.java line 45:
>>
>>> 43: * Pass {@code "jar"} as the name to
>>> 44: * {@link java.util.spi.ToolProvider#findFirst
>>> ToolProvider.findFirst}
>>> 45: * in order to obtain an instance of the tool.
>>
>> I'm not sure about the wording. It might be better to say that it provides a
>> tool named "jar". Invoke findFirst("jar") to create an instance of this tool.
>
> What is "it" in "it provides..." ?
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.
* ...
*/
-
PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Wed, 9 Feb 2022 20:33:02 GMT, Alan Bateman wrote:
>> A number of modules declare that the "provide" ToolProvider.
>>
>> These modules now specify the "name" of the argument used by
>> `ToolProvider.findFirst` to access an instance of the tool provider within
>> the description part of a `@provides` API tag.
>
> src/jdk.jartool/share/classes/module-info.java line 45:
>
>> 43: * Pass {@code "jar"} as the name to
>> 44: * {@link java.util.spi.ToolProvider#findFirst
>> ToolProvider.findFirst}
>> 45: * in order to obtain an instance of the tool.
>
> I'm not sure about the wording. It might be better to say that it provides a
> tool named "jar". Invoke findFirst("jar") to create an instance of this tool.
What is "it" in "it provides..." ?
-
PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Wed, 9 Feb 2022 16:37:00 GMT, Christian Stein wrote:
> A number of modules declare that the "provide" ToolProvider.
>
> These modules now specify the "name" of the argument used by
> `ToolProvider.findFirst` to access an instance of the tool provider within
> the description part of a `@provides` API tag.
src/jdk.jartool/share/classes/module-info.java line 45:
> 43: * Pass {@code "jar"} as the name to
> 44: * {@link java.util.spi.ToolProvider#findFirst
> ToolProvider.findFirst}
> 45: * in order to obtain an instance of the tool.
I'm not sure about the wording. It might be better to say that it provides a
tool named "jar". Invoke findFirst("jar") to create an instance of this tool.
-
PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Wed, 9 Feb 2022 16:37:00 GMT, Christian Stein wrote:
> A number of modules declare that the "provide" ToolProvider.
>
> These modules now specify the "name" of the argument used by
> `ToolProvider.findFirst` to access an instance of the tool provider within
> the description part of a `@provides` API tag.
> Would it be more pedantically accurate to talk about getting an instance of
> the tool provider (not just tool)?
Yes. That would be more correct.
My wording was aligned to the one used in the main description block, which
also talks about "tool(s)". For example:
* Instances of the tools can be obtained by calling
* {@link java.util.spi.ToolProvider#findFirst ToolProvider.findFirst}
* or the {@linkplain java.util.ServiceLoader service loader} with the name
* {@code "javac"}.
_Here, it should read "Instances of the tool can be..." and not "Instances of
the tools can be..." - right? As there's only a single one provided by this
module._
-
PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Wed, 9 Feb 2022 16:37:00 GMT, Christian Stein wrote: > A number of modules declare that the "provide" ToolProvider. > > These modules now specify the "name" of the argument used by > `ToolProvider.findFirst` to access an instance of the tool provider within > the description part of a `@provides` API tag. Would it be more pedantically accurate to talk about getting an instance of the _tool provider_ (not just _tool_)? - Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Wed, 9 Feb 2022 16:37:00 GMT, Christian Stein wrote: > A number of modules declare that the "provide" ToolProvider. > > These modules now specify the "name" of the argument used by > `ToolProvider.findFirst` to access an instance of the tool provider within > the description part of a `@provides` API tag. Marked as reviewed by lancea (Reviewer). - PR: https://git.openjdk.java.net/jdk/pull/7406
Re: RFR: 8280825: Modules that "provide" ToolProvider should document the name that can be used
On Wed, 9 Feb 2022 16:37:00 GMT, Christian Stein wrote: > A number of modules declare that the "provide" ToolProvider. > > These modules now specify the "name" of the argument used by > `ToolProvider.findFirst` to access an instance of the tool provider within > the description part of a `@provides` API tag. Minor format suggestion: add a newline after the service name, to start the description on its own line, as in: @provides This form would extend well to any modules that provide the service in different ways ... i.e. with different names for `TP.findFirst` to obtain different instances. - PR: https://git.openjdk.java.net/jdk/pull/7406
