Extend documentation for QFile:copy()

- Add information about symlinks and file metadata.
- Reflow text.
- Extract text common to both overloads to a .qdocinc file
  for consistency and to avoid duplication.

Fixes: QTBUG-94706
Change-Id: I3c730fd63f4018a1a573bb56751fedd2270a3247
Reviewed-by: Thiago Macieira <thiago.macieira@intel.com>
(cherry picked from commit cc2fdce35e6a958e021b4d4cdc0ace1a91b06d0c)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

1 files changed, 11 insertions, 0 deletions

diff --git a/src/corelib/doc/src/includes/qfile-copy.qdocinc b/src/corelib/doc/src/includes/qfile-copy.qdocinc
new file mode 100644
index 0000000000..5ff68eac81
--- /dev/null
+++ b/src/corelib/doc/src/includes/qfile-copy.qdocinc
@@ -0,0 +1,11 @@
+This file is closed before it is copied.
+
+If the copied file is a symbolic link (symlink), the
+file it refers to is copied, not the link itself. With the
+exception of permissions, which are copied, no other file metadata
+is copied.
+
+Returns \c true if successful; otherwise returns \c false.
+
+Note that if a file with the name \a newName already exists,
+copy() returns \c false. This means QFile will not overwrite it.