From e22bc8fcdc07890c76b02f99dd06bef79ff3db9c Mon Sep 17 00:00:00 2001 From: Ahmad Samir Date: Tue, 23 Jan 2024 14:54:57 +0200 Subject: [PATCH] QFileInfo: de-duplicate docs wrt. fetching info of a symlink's target Not the symlink itself. Drive-by change: fix a typo, `treats` not `threats` :) Pick-to: 6.6 6.5 Change-Id: Iac793cf80bdd17e6424e877de780fce0b28236bb Reviewed-by: Thiago Macieira Reviewed-by: Leena Miettinen (cherry picked from commit 5ae4e1a2936683abd94c4a66d2fcb277d756f866) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/io/qfileinfo.cpp | 86 ++++++++++++++---------------------- 1 file changed, 34 insertions(+), 52 deletions(-) diff --git a/src/corelib/io/qfileinfo.cpp b/src/corelib/io/qfileinfo.cpp index 19adede02d7..7059cdd9a11 100644 --- a/src/corelib/io/qfileinfo.cpp +++ b/src/corelib/io/qfileinfo.cpp @@ -926,8 +926,7 @@ QDir QFileInfo::absoluteDir() const /*! Returns \c true if the user can read the file; otherwise returns \c false. - If the file is a symlink, this function returns true if the target is - readable (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \note If the \l{NTFS permissions} check has not been enabled, the result on Windows will merely reflect whether the file exists. @@ -946,8 +945,7 @@ bool QFileInfo::isReadable() const /*! Returns \c true if the user can write to the file; otherwise returns \c false. - If the file is a symlink, this function returns true if the target is - writeable (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \note If the \l{NTFS permissions} check has not been enabled, the result on Windows will merely reflect whether the file is marked as Read Only. @@ -966,8 +964,10 @@ bool QFileInfo::isWritable() const /*! Returns \c true if the file is executable; otherwise returns \c false. - If the file is a symlink, this function returns true if the target is - executable (not the symlink). +//! [info-about-target-not-symlink] + If the file is a symlink, this function returns information about the + target, not the symlink. +//! [info-about-target-not-symlink] \sa isReadable(), isWritable(), permission() */ @@ -984,7 +984,7 @@ bool QFileInfo::isExecutable() const Returns \c true if this is a `hidden' file; otherwise returns \c false. \b{Note:} This function returns \c true for the special entries "." and - ".." on Unix, even though QDir::entryList threats them as shown. And note + ".." on Unix, even though QDir::entryList treats them as shown. And note that, since this function inspects the file name, on Unix it will inspect the name of the symlink, if this file is a symlink, not the target's name. @@ -1029,8 +1029,7 @@ bool QFileInfo::isNativePath() const object points to something that is not a file (such as a directory) or that does not exist. - If the file is a symlink, this function returns true if the target is a - regular file (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa isDir(), isSymLink(), isBundle() */ @@ -1049,8 +1048,7 @@ bool QFileInfo::isFile() const object points to something that is not a directory (such as a file) or that does not exist. - If the file is a symlink, this function returns true if the target is a - directory (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa isFile(), isSymLink(), isBundle() */ @@ -1069,8 +1067,7 @@ bool QFileInfo::isDir() const Returns \c true if this object points to a bundle or to a symbolic link to a bundle on \macos and iOS; otherwise returns \c false. - If the file is a symlink, this function returns true if the target is a - bundle (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa isDir(), isSymLink(), isFile() */ @@ -1101,8 +1098,10 @@ bool QFileInfo::isBundle() const \snippet code/src_corelib_io_qfileinfo.cpp 9 - \note If the symlink points to a non existing file, exists() returns - false. +//! [symlink-target-exists-behavior] + \note exists() returns \c true if the symlink points to an existing + target, otherwise it returns \c false. +//! [symlink-target-exists-behavior] \sa isFile(), isDir(), symLinkTarget() */ @@ -1130,8 +1129,7 @@ bool QFileInfo::isSymLink() const (\c *.lnk files) on Windows and aliases on \macos. Use QFileInfo::isShortcut() and QFileInfo::isAlias() instead. - \note If the symlink points to a non existing file, exists() returns - false. + \include qfileinfo.cpp symlink-target-exists-behavior \sa isFile(), isDir(), isShortcut(), symLinkTarget() */ @@ -1250,8 +1248,8 @@ bool QFileInfo::isRoot() const link. This name may not represent an existing file; it is only a string. - QFileInfo::exists() returns \c true if the symlink points to an - existing file. + + \include qfileinfo.cpp symlink-target-exists-behavior \sa exists(), isSymLink(), isDir(), isFile() */ @@ -1313,8 +1311,7 @@ QString QFileInfo::junctionTarget() const milliseconds). On Windows, it will return an empty string unless the \l{NTFS permissions} check has been enabled. - If the file is a symlink, this function returns the owner of the target - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa ownerId(), group(), groupId() */ @@ -1332,8 +1329,7 @@ QString QFileInfo::owner() const On Windows and on systems where files do not have owners this function returns ((uint) -2). - If the file is a symlink, this function returns the id of the owner of the target - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa owner(), group(), groupId() */ @@ -1354,8 +1350,7 @@ uint QFileInfo::ownerId() const This function can be time consuming under Unix (in the order of milliseconds). - If the file is a symlink, this function returns the owning group of the - target (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa groupId(), owner(), ownerId() */ @@ -1373,8 +1368,7 @@ QString QFileInfo::group() const On Windows and on systems where files do not have groups this function always returns (uint) -2. - If the file is a symlink, this function returns the id of the group owning the - target (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa group(), owner(), ownerId() */ @@ -1401,8 +1395,7 @@ uint QFileInfo::groupId() const Example: \snippet code/src_corelib_io_qfileinfo.cpp 10 - If the file is a symlink, this function checks the permissions of the - target (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa isReadable(), isWritable(), isExecutable() */ @@ -1427,8 +1420,7 @@ bool QFileInfo::permission(QFile::Permissions permissions) const \note The result might be inaccurate on Windows if the \l{NTFS permissions} check has not been enabled. - If the file is a symlink, this function returns the permissions of the - target (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink */ QFile::Permissions QFileInfo::permissions() const { @@ -1446,8 +1438,7 @@ QFile::Permissions QFileInfo::permissions() const Returns the file size in bytes. If the file does not exist or cannot be fetched, 0 is returned. - If the file is a symlink, the size of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \sa exists() */ @@ -1473,7 +1464,7 @@ qint64 QFileInfo::size() const If the file birth time is not available, this function returns an invalid QDateTime. - If the file is a symlink, the time of the target file is returned (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink This function overloads QFileInfo::birthTime(const QTimeZone &tz), and returns the same as \c{birthTime(QTimeZone::LocalTime)}. @@ -1492,8 +1483,7 @@ qint64 QFileInfo::size() const If the file birth time is not available, this function returns an invalid QDateTime. - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \since 6.6 \sa lastModified(const QTimeZone &), lastRead(const QTimeZone &), @@ -1511,8 +1501,7 @@ qint64 QFileInfo::size() const occurs whenever the user writes or sets inode information (for example, changing the file permissions). - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink This function overloads QFileInfo::metadataChangeTime(const QTimeZone &tz), and returns the same as \c{metadataChangeTime(QTimeZone::LocalTime)}. @@ -1531,8 +1520,7 @@ qint64 QFileInfo::size() const \include qfileinfo.cpp file-times-in-time-zone - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \since 6.6 \sa birthTime(const QTimeZone &), lastModified(const QTimeZone &), @@ -1545,8 +1533,7 @@ qint64 QFileInfo::size() const Returns the date and time when the file was last modified. - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink This function overloads \l{QFileInfo::lastModified(const QTimeZone &)}, and returns the same as \c{lastModified(QTimeZone::LocalTime)}. @@ -1561,8 +1548,7 @@ qint64 QFileInfo::size() const \include qfileinfo.cpp file-times-in-time-zone - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \since 6.6 \sa birthTime(const QTimeZone &), lastRead(const QTimeZone &), @@ -1578,8 +1564,7 @@ qint64 QFileInfo::size() const On platforms where this information is not available, returns the same time as lastModified(). - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink This function overloads \l{QFileInfo::lastRead(const QTimeZone &)}, and returns the same as \c{lastRead(QTimeZone::LocalTime)}. @@ -1597,8 +1582,7 @@ qint64 QFileInfo::size() const On platforms where this information is not available, returns the same time as lastModified(). - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \since 6.6 \sa birthTime(const QTimeZone &), lastModified(const QTimeZone &), @@ -1612,8 +1596,7 @@ qint64 QFileInfo::size() const If the time cannot be determined, an invalid date time is returned. - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink This function overloads \l{QFileInfo::fileTime(QFileDevice::FileTime, const QTimeZone &)}, @@ -1640,8 +1623,7 @@ QDateTime QFileInfo::fileTime(QFile::FileTime time) const { If the time cannot be determined, an invalid date time is returned. - If the file is a symlink, the time of the target file is returned - (not the symlink). + \include qfileinfo.cpp info-about-target-not-symlink \since 6.6 \sa birthTime(const QTimeZone &), lastModified(const QTimeZone &),