RFR: 8266631: StandardJavaFileManager: getJavaFileObjects() impl violates the spec

[Jonathan Gibbons]

On Fri, 4 Jun 2021 12:42:35 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> This improves javadoc/specification of several StandardJavaFileManager methods, as requested in these bugs:
> https://bugs.openjdk.java.net/browse/JDK-8266631
> https://bugs.openjdk.java.net/browse/JDK-8266596
> https://bugs.openjdk.java.net/browse/JDK-8266591
> https://bugs.openjdk.java.net/browse/JDK-8266590
> 
> The CSR is here:
> https://bugs.openjdk.java.net/browse/JDK-8268260

Changes requested by jjg (Reviewer).

src/java.compiler/share/classes/javax/tools/StandardJavaFileManager.java line 195:

> 193:      * The default implementation lazily converts each path to a file and calls
> 194:      * {@link #getJavaFileObjectsFromFiles(Iterable) getJavaFileObjectsFromFiles}.
> 195:      * IllegalArgumentException will be thrown if any of the paths

since we're editing lines in this region ... use {@code} or {@link} around IllegalArgumentException.

src/java.compiler/share/classes/javax/tools/StandardJavaFileManager.java line 199:

> 197:      *
> 198:      * @param paths a list of paths
> 199:      * @return a list of file objects

In the following @throws, remove the trailing "."

src/java.compiler/share/classes/javax/tools/StandardJavaFileManager.java line 217:

> 215:      * The default implementation lazily converts each path to a file and calls
> 216:      * {@link #getJavaFileObjectsFromPaths(Collection) getJavaFileObjectsFromPaths}.
> 217:      * IllegalArgumentException will be thrown if any of the paths

since we're editing lines in this region ... use {@code} or {@link} around IllegalArgumentException.

src/java.compiler/share/classes/javax/tools/StandardJavaFileManager.java line 268:

> 266:      * @return a list of file objects
> 267:      * @throws IllegalArgumentException if the array of files includes
> 268:      * a directory

consider adding ` or if this file manager does not support any of the
     * given paths` in line with similar methods

src/java.compiler/share/classes/javax/tools/StandardJavaFileManager.java line 271:

> 269:      * @throws NullPointerException if the given array contains null
> 270:      * elements and the given element is used by
> 271:      * {@linkplain #getJavaFileObjectsFromPaths(Collection)}.

The new condition should be in an `@implSpec`.

The package declaration contains a general specification for nulls and NPE, so it's not clear that we need the `@throws NPE` at all, but it's not wrong to leave it as was.

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

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