Summary

Add a sentence to java.nio.file.Files.createLink to highlight the behavior when the existing parameter is the path to a symbolic link.

Problem

Files.createLink when invoked with its existing parameter representing a symbolic link behaves differently on different operating systems. On Linux and Windows the created link is for the symbolic link itself, whereas on macOS, it is for the target of the symbolic link.

Solution

Add a sentence to the description of Files.createLink calling out the unspecified behavior.

Specification

--- a/src/java.base/share/classes/java/nio/file/Files.java
+++ b/src/java.base/share/classes/java/nio/file/Files.java
@@ -982,7 +982,10 @@ public static Path createSymbolicLink(Path link, Path target,
      * The {@code existing} parameter is the path to an existing file. This
      * method creates a new directory entry for the file so that it can be
      * accessed using {@code link} as the path. On some file systems this is
-     * known as creating a "hard link". Whether the file attributes are
+     * known as creating a "hard link". If the {@code existing} parameter
+     * is the path to a symbolic link, then whether the new link is for the
+     * target of the symbolic link or for the symbolic link itself is platform
+     * dependent and therefore not specified. Whether the file attributes are
      * maintained for the file or for each directory entry is file system
      * specific and therefore not specified. Typically, a file system requires
      * that all links (directory entries) for a file be on the same file system.