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

[Jan Lahoda]

> [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

Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains four additional commits since the last revision:

 - Using @code instead of @linkplain, as suggested.
 - Merge branch 'master' into JDK-8266631
 - Improving javadoc as suggested on the review.
 - 8266631: StandardJavaFileManager: getJavaFileObjects() impl violates the spec

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

Changes:
  - all: https://git.openjdk.java.net/jdk17/pull/56/files
  - new: https://git.openjdk.java.net/jdk17/pull/56/files/3136b328..3f22cb02

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk17&pr=56&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk17&pr=56&range=00-01

  Stats: 48465 lines in 882 files changed: 37419 ins; 6396 del; 4650 mod
  Patch: https://git.openjdk.java.net/jdk17/pull/56.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk17 pull/56/head:pull/56

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