QDir/QFileInfo: add doc notes about paths starting with ':'

This is an addendum to commit 0da5726a43b; making the note about paths
starting with ':' being treated as absolute paths by the underlying
QFileSystemEngine, more visible, so that users of the class don't hit
that pitfall.

Add similar docs to QFileInfo.

Change-Id: Ib34d066d31bb673d340ec41422ed4daf911765b8
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit 138fa9f2f4445832769a126a8ea72686b3687933)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 27 insertions, 7 deletions

diff --git a/src/corelib/io/qdir.cpp b/src/corelib/io/qdir.cpp
index a9c20ba5cc..8452e3d324 100644
--- a/src/corelib/io/qdir.cpp
+++ b/src/corelib/io/qdir.cpp
@@ -418,6 +418,9 @@ inline void QDirPrivate::initFileEngine()
     a QDir is using a relative or an absolute file path. Call
     makeAbsolute() to convert a relative QDir to an absolute one.
 
+    \note Paths starting with a colon (\e{:}) are always considered
+    absolute, as they denote a QResource.
+
     \section1 Navigation and Directory Operations
 
     A directory's path can be obtained with the path() function, and
@@ -1709,6 +1712,9 @@ bool QDir::isRoot() const
     Returns \c true if the directory's path is absolute; otherwise
     returns \c false. See isAbsolutePath().
 
+    \note Paths starting with a colon (\e{:}) are always considered
+    absolute, as they denote a QResource.
+
     \sa isRelative(), makeAbsolute(), cleanPath()
 */
 
@@ -1718,9 +1724,8 @@ bool QDir::isRoot() const
     Returns \c true if \a path is absolute; returns \c false if it is
     relative.
 
-    \note If \a path starts with ':', this function will return \c true
-    because paths starting with ':' are treated specially as they denote
-    a QResource.
+    \note Paths starting with a colon (\e{:}) are always considered
+    absolute, as they denote a QResource.
 
     \sa isAbsolute(), isRelativePath(), makeAbsolute(), cleanPath(), QResource
 */
@@ -1730,6 +1735,9 @@ bool QDir::isRoot() const
     false. (Under Unix a path is relative if it does not start with a
     "/").
 
+    \note Paths starting with a colon (\e{:}) are always considered
+    absolute, as they denote a QResource.
+
     \sa makeAbsolute(), isAbsolute(), isAbsolutePath(), cleanPath()
 */
 bool QDir::isRelative() const
@@ -2396,6 +2404,9 @@ QString QDir::cleanPath(const QString &path)
     Returns \c true if \a path is relative; returns \c false if it is
     absolute.
 
+    \note Paths starting with a colon (\e{:}) are always considered
+    absolute, as they denote a QResource.
+
     \sa isRelative(), isAbsolutePath(), makeAbsolute()
 */
 bool QDir::isRelativePath(const QString &path)
diff --git a/src/corelib/io/qfileinfo.cpp b/src/corelib/io/qfileinfo.cpp
index d900513295..c059508c9a 100644
--- a/src/corelib/io/qfileinfo.cpp
+++ b/src/corelib/io/qfileinfo.cpp
@@ -241,6 +241,9 @@ QDateTime &QFileInfoPrivate::getFileTime(QAbstractFileEngine::FileTime request)
     path. You can call the function makeAbsolute() to convert a
     relative QFileInfo's path to an absolute path.
 
+    \note Paths starting with a colon (\e{:}) are always considered
+    absolute, as they denote a QResource.
+
     The file that the QFileInfo works on is set in the constructor or
     later with setFile(). Use exists() to see if the file exists and
     size() to get its size.
@@ -632,17 +635,23 @@ QString QFileInfo::path() const
 /*!
     \fn bool QFileInfo::isAbsolute() const
 
-    Returns \c true if the file path name is absolute, otherwise returns
-    false if the path is relative.
+    Returns \c true if the file path is absolute, otherwise returns \c false (i.e.
+    the path is relative).
+
+    \note Paths starting with a colon (\e{:}) are always considered absolute, as
+    they denote a QResource.
 
     \sa isRelative()
 */
 
 /*!
-    Returns \c true if the file path name is relative, otherwise returns
-    false if the path is absolute (e.g. under Unix a path is absolute
+    Returns \c true if the file path is relative, otherwise returns \c
+    false (i.e. the path is absolute). (E.g. under Unix a path is absolute
     if it begins with a "/").
 
+    \note Paths starting with a colon (\e{:}) are always considered absolute,
+    as they denote a QResource.
+
     \sa isAbsolute()
 */
 bool QFileInfo::isRelative() const