Improve documentation of Sys.remove

1 files changed, 7 insertions, 4 deletions

diff --git a/stdlib/sys.mli b/stdlib/sys.mli
index 76269887e0..715e119c13 100644
--- a/stdlib/sys.mli
+++ b/stdlib/sys.mli
@@ -43,10 +43,13 @@ external remove : string -> unit = "caml_sys_remove"
 (** Remove the given file name from the file system. *)
 
 external rename : string -> string -> unit = "caml_sys_rename"
-(** Rename a file. The first argument is the old name and the
-   second is the new name. If there is already another file
-   under the new name, [rename] will delete it before the rename,
-   effectively replacing its contents.
+(** Rename a file.  [rename oldpath newpath] renames the file
+    called [oldpath], giving it [newpath] as its new name,
+    moving it between directories if needed.  If [newpath] already
+    exists, its contents will be replaced with those of [oldpath].
+    Depending on the operating system, the metadata (permissions,
+    owner, etc) of [newpath] can either be preserved or be replaced by
+    those of [oldpath].
    @since 4.06 concerning the "replace existing file" behavior *)
 
 external getenv : string -> string = "caml_sys_getenv"