Re #132 Extend Haddock docs to be express about Windows limitation

haskell · Sep 26, 2023 · 1751cfa · 1751cfa
1 parent e7988c9
commit 1751cfa
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 6 deletions.
diff --git a/System/Directory.hs b/System/Directory.hs
@@ -458,9 +458,13 @@ renameDirectory opath npath = do
 {- |@'renameFile' old new@ changes the name of an existing file system
 object from /old/ to /new/.  If the /new/ object already exists, it is
 replaced by the /old/ object.  Neither path may refer to an existing
-directory.  A conformant implementation need not support renaming files
-in all situations (e.g. renaming across different physical devices), but
-the constraints must be documented.
+directory.
+
+A conformant implementation need not support renaming files in all situations
+(e.g. renaming across different physical devices), but the constraints must be
+documented. On Windows, this does not support renaming across different physical
+devices; if you are looking to do so, consider using 'copyFileWithMetadata' and
+'removeFile'.
 
 On Windows, this calls @MoveFileEx@ with @MOVEFILE_REPLACE_EXISTING@ set,
 which is not guaranteed to be atomic

diff --git a/System/Directory/OsPath.hs b/System/Directory/OsPath.hs
@@ -588,9 +588,13 @@ renameDirectory opath npath =
 {- |@'renameFile' old new@ changes the name of an existing file system
 object from /old/ to /new/.  If the /new/ object already exists, it is
 replaced by the /old/ object.  Neither path may refer to an existing
-directory.  A conformant implementation need not support renaming files
-in all situations (e.g. renaming across different physical devices), but
-the constraints must be documented.
+directory.
+
+A conformant implementation need not support renaming files in all situations
+(e.g. renaming across different physical devices), but the constraints must be
+documented. On Windows, this does not support renaming across different physical
+devices; if you are looking to do so, consider using 'copyFileWithMetadata' and
+'removeFile'.
 
 On Windows, this calls @MoveFileEx@ with @MOVEFILE_REPLACE_EXISTING@ set,
 which is not guaranteed to be atomic