RFR: 8286654: Add an optional description accessor on ToolProvider interface

[Christian Stein]

On Wed, 18 May 2022 21:47:25 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This PR adds an optional description accessor on `ToolProvider` interface.
>> 
>> This PR also adds short description for each of the listed tool:
>> - `jar`
>> - `javac`
>> - `javadoc`
>> - `javap` and `jdeps`
>> - `jlink` and `jmod`
>> - `jpackage`
>
> src/jdk.compiler/share/classes/com/sun/tools/javac/main/JavacToolProvider.java line 30:
> 
>> 28: import com.sun.tools.javac.util.JavacMessages;
>> 29: import java.io.PrintWriter;
>> 30: import java.util.Optional;
> 
> at least in javac, we normally sort `java.*` and `javax.*` imports before other imports.

Sorted imports accordingly.

> src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties line 387:
> 
>> 385: 
>> 386: javac.description=Read Java declarations and compile them into class files
>> 387: 
> 
> for your general consideration, what grammatical style do you recommend here? Should it be 3rd person (Reads) instead of 2nd person (Read)

I took the phrases in 2nd person style from https://docs.oracle.com/en/java/javase/18/docs/specs/man/ as templates, shortening some of them to around 80 characters for better fitting in standard terminal widths.

Perhaps, those texts should be used "as-is" as descriptions?
- 2nd person phrase-style
- lowercase start
- no terminating period
- no shortening

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

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