Docs: add doc-string for BLI_rename

Since this may delete the destination file,
it's important to note when that happens.

Also note why path comparison isn't used in code-comments.

source/blender/blenlib/BLI_fileops.h

@@ -40,6 +40,17 @@ extern "C" {
 int BLI_exists(const char *path) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL();
 int BLI_copy(const char *file, const char *to) ATTR_NONNULL();
 /**
+ * Rename a file or directory.
+ *
+ * \warning It's up to the caller to ensure `from` & `to` don't point to the same file
+ * as this will result in `to` being deleted to make room for `from`
+ * (which will then also be deleted).
+ *
+ * See #BLI_path_move to move directories.
+ *
+ * \param from: The path to rename from (return failure if it does not exist).
+ * \param to: The destination path.
+ * This will be deleted if it already exists, unless it's a directory which will fail.
  * \return zero on success (matching 'rename' behavior).
  */
 int BLI_rename(const char *from, const char *to) ATTR_NONNULL();

source/blender/blenlib/intern/fileops.c

@@ -385,6 +385,19 @@ int BLI_rename(const char *from, const char *to)
     return 1;
   }
 
+  /* NOTE(@ideasman42): there are no checks that `from` & `to` *aren't* the same file.
+   * It's up to the caller to ensure this. In practice these paths are often generated
+   * and known to be different rather than arbitrary user input.
+   * In the case of arbitrary paths (renaming a file in the file-selector for example),
+   * the caller must ensure file renaming doesn't cause user data loss.
+   *
+   * Support for checking the files aren't the same could be added, however path comparison
+   * alone is *not* a guarantee the files are different (given the possibility of accessing
+   * the same file through different paths via symbolic-links), we could instead support a
+   * verizon of Python's * `os.path.samefile(..)` which compares the I-node & device.
+   * In this particular case we would not want to follow symbolic-links as well.
+   * Since this functionality isn't required at the moment, leave this as-is.
+   * Noting it as a potential improvement. */
   if (BLI_exists(to)) {
     if (BLI_delete(to, false, false)) {
       return 1;