From adaf1fb107ceb7003313ceb67605f986b74763b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kai=20K=C3=B6hne?= Date: Thu, 5 Dec 2024 16:25:23 +0100 Subject: [PATCH] Doc: Improve QTemporaryFile::open() descriptions Explain the behavior of open() in detail, including the edge cases (reopening a file). Fix links to QIODeviceBase::OpenMode flags. Use explicit links to make linking more robust. Use the same parameter name 'mode' as in the base class. Pick-to: 6.8 6.9 Task-number: QTBUG-131484 Change-Id: I5d01b3bb48a7a439b93c144e6d38482607de8d33 Reviewed-by: Thiago Macieira --- src/corelib/io/qtemporaryfile.cpp | 43 +++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/src/corelib/io/qtemporaryfile.cpp b/src/corelib/io/qtemporaryfile.cpp index 74a6f731cb8..6fb543d8696 100644 --- a/src/corelib/io/qtemporaryfile.cpp +++ b/src/corelib/io/qtemporaryfile.cpp @@ -736,14 +736,21 @@ QTemporaryFile::~QTemporaryFile() } /*! - \fn bool QTemporaryFile::open() + \fn bool QTemporaryFile::open() - A QTemporaryFile will always be opened in QIODevice::ReadWrite mode, - this allows easy access to the data in the file. This function will - return true upon success and will set the fileName() to the unique - filename used. + Opens a unique temporary file in the file system in + \l QIODeviceBase::ReadWrite mode. + Returns \c true if the file was successfully opened, or was already open. + Otherwise returns \c false. - \sa fileName(), QT_USE_NODISCARD_FILE_OPEN + If called for the first time, open() will create a unique file name + based on \l fileTemplate(). The file is guaranteed to have been created + by this function (that is, it has never existed before). + + If a file is reopened after calling \l close(), the same file will be + opened again. + + \sa setFileTemplate(), QT_USE_NODISCARD_FILE_OPEN */ /*! @@ -964,18 +971,28 @@ QTemporaryFile *QTemporaryFile::createNativeFile(QFile &file) } /*! - \reimp + \reimp - Creates a unique file name for the temporary file, and opens it. You can - get the unique name later by calling fileName(). The file is guaranteed to - have been created by this function (i.e., it has never existed before). + Opens a unique temporary file in the file system with \a mode flags. + Returns \c true if the file was successfully opened, or was already open. + Otherwise returns \c false. + + If called for the first time, open() will create a unique file name + based on \l fileTemplate(), and open it with \a mode flags. + The file is guaranteed to have been created by this function (that is, + it has never existed before). + + If a file is reopened after calling \l close(), the same file will be + opened again with \a mode flags. + + \sa setFileTemplate(), QT_USE_NODISCARD_FILE_OPEN */ -bool QTemporaryFile::open(OpenMode flags) +bool QTemporaryFile::open(OpenMode mode) { Q_D(QTemporaryFile); auto tef = static_cast(d->fileEngine.get()); if (tef && tef->isReallyOpen()) { - setOpenMode(flags); + setOpenMode(mode); return true; } @@ -986,7 +1003,7 @@ bool QTemporaryFile::open(OpenMode flags) // d->engine(); d->resetFileEngine(); - if (QFile::open(flags)) { + if (QFile::open(mode)) { tef = static_cast(d->fileEngine.get()); if (tef->isUnnamedFile()) d->fileName.clear();