RFR: 8220816: (fs) Files.createDirectory should make it more obvious that it fails when the directory already exists [v4]

[Alan Bateman]

On Wed, 19 Nov 2025 18:12:32 GMT, Brian Burkhalter <bpb at openjdk.org> wrote:

>> Slightly changes the specification of `Files.createDirectory` to highlight that it fails if a filesystem entity already exists at the given location.
>
> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
> 
>   8220816: Improve consistency per review comments

src/java.base/share/classes/java/nio/file/Files.java line 579:

> 577:     /**
> 578:      * Creates a new and empty file, failing if {@code path} locates an existing
> 579:      * file. The

That works. I assume you'll re-flow this a bit to avoid "file. The"  be on its own.

src/java.base/share/classes/java/nio/file/Files.java line 681:

> 679:      *          when creating the directory
> 680:      * @throws  FileAlreadyExistsException
> 681:      *          if {@code dir} locates an existing file but is not a directory

Maybe "that is not a directory" might be better.

src/java.base/share/classes/java/nio/file/Files.java line 985:

> 983:     /**
> 984:      * Creates a new link (directory entry) for an existing file,
> 985:     * failing if {@code link} locates an existing file <i>(optional

Minor nit, I think the comment has got mis-aligned.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/28378#discussion_r2543185333
PR Review Comment: https://git.openjdk.org/jdk/pull/28378#discussion_r2543183191
PR Review Comment: https://git.openjdk.org/jdk/pull/28378#discussion_r2543187478