From 979b602307874e0768b242e46dd7de024ac0eb3e Mon Sep 17 00:00:00 2001
From: Thiago Macieira <thiago.macieira@intel.com>
Date: Fri, 19 Jan 2024 11:32:01 -0800
Subject: [PATCH] QFile::moveToTrash: add documentation about run time and fail
 conditions

All of the implementations will attempt to perform a filesystem rename,
so the runtime is constant for a single file and possibly for a
directory full of files too.

The macOS and Windows implementations use the OS API so they run with
slightly elevated privileges. That means they don't fail under normal
conditions. The XDG implementation will fail if the file or dir being
trashed resides on a volume which doesn't have an existing trash
location for the current user and one such cannot be created either, or
if the hardlinking/renaming fails (usually with EXDEV).

Change-Id: I76ffba14ece04f24b43efffd17abd67e20196f2b
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@qt.io>
(cherry picked from commit 6d1b4d574021bc2d036e61526b01a2dea5876b5b)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
(cherry picked from commit acdaef4ebd417322b759c6974d55192f057be979)
---
 .../externalsites/external-resources.qdoc     |  5 +++++
 src/corelib/io/qfile.cpp                      | 21 +++++++++++++++++++
 2 files changed, 26 insertions(+)

diff --git a/doc/global/externalsites/external-resources.qdoc b/doc/global/externalsites/external-resources.qdoc
index 3bf48bfd3b3..bd1292f4c8e 100644
--- a/doc/global/externalsites/external-resources.qdoc
+++ b/doc/global/externalsites/external-resources.qdoc
@@ -566,3 +566,8 @@
     \externalpage https://www.qt.io/product/quality-assurance/test-center
     \title Test Center
 */
+
+/*!
+    \externalpage https://specifications.freedesktop.org/trash-spec/trashspec-1.0.html
+    \title FreeDesktop.org Trash specification version 1.0
+*/
diff --git a/src/corelib/io/qfile.cpp b/src/corelib/io/qfile.cpp
index 136906a80d5..8a2b766530d 100644
--- a/src/corelib/io/qfile.cpp
+++ b/src/corelib/io/qfile.cpp
@@ -459,6 +459,24 @@ QFile::remove(const QString &fileName)
     and sets the fileName() to the path at which the file can be found within the trash;
     otherwise returns \c false.
 
+//! [move-to-trash-common]
+    The time for this function to run is independent of the size of the file
+    being trashed. If this function is called on a directory, it may be
+    proportional to the number of files being trashed.
+
+    This function uses the Windows and \macos APIs to perform the trashing on
+    those two operating systems. Elsewhere (Unix systems), this function
+    implements the \l{FreeDesktop.org Trash specification version 1.0}.
+
+    \note When using the FreeDesktop.org Trash implementation, this function
+    will fail if it is unable to move the files to the trash location by way of
+    file renames and hardlinks. This condition arises if the file being trashed
+    resides on a volume (mount point) on which the current user does not have
+    permission to create the \c{.Trash} directory, or with some unusual
+    filesystem types or configurations (such as sub-volumes that aren't
+    themselves mount points).
+//! [move-to-trash-common]
+
     \note On systems where the system API doesn't report the location of the file in the
     trash, fileName() will be set to the null string once the file has been moved. On
     systems that don't have a trash can, this function always returns false.
@@ -496,9 +514,12 @@ QFile::moveToTrash()
     and sets \a pathInTrash (if provided) to the path at which the file can be found within
     the trash; otherwise returns \c false.
 
+    \include qfile.cpp move-to-trash-common
+
     \note On systems where the system API doesn't report the path of the file in the
     trash, \a pathInTrash will be set to the null string once the file has been moved.
     On systems that don't have a trash can, this function always returns false.
+
 */
 bool
 QFile::moveToTrash(const QString &fileName, QString *pathInTrash)