[jdk17] RFR: 8266631: StandardJavaFileManager: getJavaFileObjects() impl violates the spec

[Jonathan Gibbons]

On Tue, 15 Jun 2021 14:26:46 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> [a copy of https://github.com/openjdk/jdk/pull/4360 for openjdk/jdk17]
> 
> 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

OK ... but please avoid using `{@linkplain}` for code constructs.  Use `{@link}` or `{@code}`

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:      * {@linkplain IllegalArgumentException IllegalArgumentException} will be thrown

Suggest using with `{@link}` or `{@code}` but not `{@linkplain}`.
Given that there is a `@throws` which will link it, `{@code}` may be enough.

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:      * {@linkplain IllegalArgumentException IllegalArgumentException} will be thrown

ditto use `{@code}`

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

> 265:      *
> 266:      * @implSpec
> 267:      * The default implementation will only throw {@linkplain NullPointerException NullPointerException}

`{@linkplain}` should only be used for natural-language text. 
Alternatively, it *may* work to use `{@linkplain NullPointerException {@code NullPointerException}}` but that seems overkill.

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

> 341:      * The default implementation lazily converts each path to a file and calls
> 342:      * {@link #setLocation setLocation}.
> 343:      * {@linkplain IllegalArgumentException IllegalArgumentException}

Ditto.

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

Marked as reviewed by jjg (Reviewer).

PR: https://git.openjdk.java.net/jdk17/pull/56