Summary

ModuleFinder.of not clear that FindException thrown if module descriptor cannot be derived for automatic module

Problem

java.lang.module.ModuleFinder is a new API introduced via CCC-8142968 to find modules. The ModuleFinder.of(Path ...) method finds modules on the file system. This method treats JAR files that do not have the binary form of a module declaration (module-info.class) as "automatic modules". The wording for how the module descriptor for an automatic module is derived does not make it clear that an exception is thrown when this process fails, say where a module name cannot be derived from the name of the JAR file.

Solution

Update ModuleFinder.of(Path...) to make it clear that FindException is thrown when a module descriptor cannot be created for an automatic module.

Specification

Add the following paragraph to ModuleFinder.of(Path...)

     * <p> If a {@code ModuleDescriptor} cannot be created (by means of the
     * {@link ModuleDescriptor.Builder ModuleDescriptor.Builder} API) for an
     * automatic module then {@code FindException} is thrown. This can arise,
     * for example, when a legal Java identifier name cannot be derived from
     * the file name of the JAR file or where a package name derived from an
     * entry ending with {@code .class} is not a legal Java identifier. </p>