RFR: 8267569: java.io.File.equals contains misleading Javadoc [v2]

[Alan Bateman]

On Fri, 28 May 2021 23:42:39 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

>> Modify the specification of `java.io.File.equals` to clarify that equality is based only on a comparison of abstract pathnames as opposed to the file system objects that the `File`s represent.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8267569: Put clarifying verbiage in an @implNote

src/java.base/share/classes/java/io/File.java line 2228:

> 2226:      * @implNote The abstract pathname equality test is equivalent to
> 2227:      *           {@code compareTo((File)obj) == 0}.  This method does not
> 2228:      *           access the file system and the file is not required to exist.

I think it might be clear to replace this with an apiNote that makes it clear to readers that this method just tests if the abstract paths are equal, it does not access the file system.

src/java.base/share/classes/java/io/File.java line 2237:

> 2235:      * @see #compareTo(File)
> 2236:      * @see java.nio.file.Files#isSameFile(Path,Path)
> 2237:      * @see java.nio.file.Path#equals(Object)

I think it could be confusing to link to Path.equals here, can this be dropped?

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

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