On Fri, 29 Aug 2025 15:57:47 GMT, Alan Bateman <al...@openjdk.org> wrote:
>> Attempt to improve the verbiage of the `java.io.File` specification to make
>> it clearer whether a given method operates only on an abstract pathname or
>> on the actual file system entry it denotes.
>
> src/java.base/share/classes/java/io/File.java line 85:
>
>> 83: * <p> Unless otherwise noted, {@linkplain java.nio.file##links symbolic
>> links}
>> 84: * are automatically redirected to the <i>target</i> of the link,
>> whether they
>> 85: * are provided by a pathname string or via a {@code File} object.
>> Methods
>
> What would you think about stealing some of the text we have in the
> java.nio.file package description and leading with that text in this
> paragraph. I'm thinking something like this:
>
> "Many operating systems and file systems have support for *symbolic links*. A
> symbolic link is a special file that serves as a reference to another file.
> Unless otherwise specified, symbolic links are transparent to applications
> and operations on files that are symbolic links are automatically redirected
> to the *target* of the link. Methods that only operate on the abstract
> pathname do not access the file system and thus do not resolve symbolic
> links."
Sounds reasonable.
> src/java.base/share/classes/java/io/File.java line 1949:
>
>> 1947: * @apiNote This method only compares the abstract pathnames;
>> 1948: * it does not access the file system and the file is not
>> required
>> 1949: * to exist.
>
> Rather than API note hen it might be better to take the second part of the
> proposed note and add it to the first paragraph of the method description.
> Can you try that and see how it reads?
Probably the same then should be done for the API note of `equals`
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/27006#discussion_r2310570047
PR Review Comment: https://git.openjdk.org/jdk/pull/27006#discussion_r2310570232
