Summary

Add new default method description() to the java.util.spi.ToolProvider interface that returns a short one-line description of the provided tool, or an empty Optional if no description is available.

Problem

There is no way for an author of a tool implementation supplying a description of the tool's purpose that can be retrieved programmatically.

Solution

Adding an optional description accessor on the ToolProvider interface.

Also, all tools in the JDK implementing the ToolProvider interface are updated to provide a short description of their purpose. This includes the jar, javac, javadoc, and jpackage tools.

Implementions are encouraged to return a description using the default locale.

As an alternative authors may override the toString() method in order to pass a description to users. This is not a good solution as users can not easily distinguish between a default and a custom string-represention.

Specification

/**
 * {@return a short description of the tool, or an empty
 * {@code Optional} if no description is available}
 *
 * @apiNote It is recommended that the description fits into a single
 * line in order to allow creating concise overviews like the following:
 * <pre>{@code
 * jar
 *   Create, manipulate, and extract an archive of classes and resources.
 * javac
 *   Read Java declarations and compile them into class files.
 * jlink
 *   Assemble a set of modules (...) into a custom runtime image.
 * }
 * </pre>
 *
 * @implSpec This implementation returns an empty {@code Optional}.
 *
 * @since 19
 */
default Optional<String> description() {
    return Optional.empty();
}