On Fri, 29 Aug 2025 15:01:51 GMT, Brian Burkhalter <b...@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."
src/java.base/share/classes/java/io/File.java line 940:
> 938: * @return {@code true} if the named file does not exist and was
> 939: * successfully created; {@code false} if the named file
> 940: * already exists, including if it is a symbolic link
Good.
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?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/27006#discussion_r2310534299
PR Review Comment: https://git.openjdk.org/jdk/pull/27006#discussion_r2310540208
PR Review Comment: https://git.openjdk.org/jdk/pull/27006#discussion_r2310539720
