Summary

Append a sentence to the specification of File.renameTo(File dest) to highlight that the File instance on which the method is invoked is immutable and not modified to refer to the abstract pathname provided via dest.

Problem

Although stated in its class documentation that a File is immutable, if a developer overlooks this statement, they could easily assume that the pathname representation internal to a File is changed to the pathname to which the entity is renamed.

Solution

Append a sentence fo the File.renameTo(File) specification making it explicit that the File instance is not itself modified.

Specification

@@ -1376,7 +1376,9 @@ public class File
      * file from one filesystem to another, it might not be atomic, and it
      * might not succeed if a file with the destination abstract pathname
      * already exists.  The return value should always be checked to make sure
-     * that the rename operation was successful.
+     * that the rename operation was successful.  As instances of {@code File}
+     * are immutable, this File object is not changed to name the destination
+     * file or directory.
      *
      * <p> Note that the {@link java.nio.file.Files} class defines the {@link
      * java.nio.file.Files#move move} method to move or rename a file in a