From 7e80af2bc281dc63f6228f02f233e0cb549d944a Mon Sep 17 00:00:00 2001 From: Ivan Solovev Date: Thu, 16 Jan 2025 16:31:12 +0100 Subject: [PATCH] QSharedPointer: document rvalue overloads of various cast methods The patch provides two documentation snippets: for an arbitrary arg and for \c {*this}. That is because qdoc does not support passing a command (e.g. \c) as a part of the snippet's parameter. Amends e95fb04202b3f786037c10942fd4e912644fd7d2. Found in Qt 6.9 API review. Change-Id: I4eed234d18e39f2fc0c30a647a423f3240e31d40 Reviewed-by: Giuseppe D'Angelo Reviewed-by: Marc Mutz (cherry picked from commit 8511149d886e5aef2a065efffc336c7b25e6540e) Reviewed-by: Qt Cherry-pick Bot --- src/corelib/tools/qsharedpointer.cpp | 108 ++++++++++++++++++++++++++- src/corelib/tools/qsharedpointer.h | 16 +++- 2 files changed, 116 insertions(+), 8 deletions(-) diff --git a/src/corelib/tools/qsharedpointer.cpp b/src/corelib/tools/qsharedpointer.cpp index e19ccca0069..767b7191a17 100644 --- a/src/corelib/tools/qsharedpointer.cpp +++ b/src/corelib/tools/qsharedpointer.cpp @@ -595,8 +595,24 @@ \sa isNull() */ +/* +//! [cast-overload-for-this] + The returned QSharedPointer shares ownership with the same set of + shared owners as \c {*this}. + + This function \l {reset()}{resets} \c {*this} to \nullptr on success. +//! [cast-overload-for-this] + +//! [cast-overload-for-arg] + The returned QSharedPointer shares ownership with the same set of + shared owners as \a {\1}. + + This function \l {reset()}{resets} \a {\1} to \nullptr on success. +//! [cast-overload-for-arg] +*/ + /*! - \fn template template QSharedPointer QSharedPointer::staticCast() const + \fn template template QSharedPointer QSharedPointer::staticCast() const & Performs a static cast from this pointer's type to \tt X and returns a QSharedPointer that shares the reference. This function can be @@ -611,7 +627,17 @@ */ /*! - \fn template template QSharedPointer QSharedPointer::dynamicCast() const + \fn template template QSharedPointer QSharedPointer::staticCast() && + \since 6.9 + \overload staticCast() + + \include qsharedpointer.cpp {cast-overload-for-this} + + \sa dynamicCast(), constCast(), qSharedPointerCast() +*/ + +/*! + \fn template template QSharedPointer QSharedPointer::dynamicCast() const & Performs a dynamic cast from this pointer's type to \tt X and returns a QSharedPointer that shares the reference. If this @@ -628,7 +654,17 @@ */ /*! - \fn template template QSharedPointer QSharedPointer::constCast() const + \fn template template QSharedPointer QSharedPointer::dynamicCast() && + \since 6.9 + \overload dynamicCast() + + \include qsharedpointer.cpp {cast-overload-for-this} + + \sa qSharedPointerDynamicCast() +*/ + +/*! + \fn template template QSharedPointer QSharedPointer::constCast() const & Performs a \tt const_cast from this pointer's type to \tt X and returns a QSharedPointer that shares the reference. This function can be @@ -639,7 +675,17 @@ */ /*! - \fn template template QSharedPointer QSharedPointer::objectCast() const + \fn template template QSharedPointer QSharedPointer::constCast() && + \since 6.9 + \overload constCast() + + \include qsharedpointer.cpp {cast-overload-for-this} + + \sa isNull(), qSharedPointerConstCast() +*/ + +/*! + \fn template template QSharedPointer QSharedPointer::objectCast() const & \since 4.6 Performs a \l qobject_cast() from this pointer's type to \tt X and @@ -656,6 +702,16 @@ \sa qSharedPointerObjectCast() */ +/*! + \fn template template QSharedPointer QSharedPointer::objectCast() && + \since 6.9 + \overload objectCast() + + \include qsharedpointer.cpp {cast-overload-for-this} + + \sa qSharedPointerObjectCast() +*/ + /*! \fn template template QSharedPointer QSharedPointer::create(Args &&... args) \overload @@ -1194,6 +1250,17 @@ \sa QSharedPointer::staticCast(), qSharedPointerDynamicCast(), qSharedPointerConstCast() */ +/*! + \fn template QSharedPointer qSharedPointerCast(QSharedPointer &&other) + \relates QSharedPointer + \since 6.9 + \overload qSharedPointerCast(const QSharedPointer &other) + + \include qsharedpointer.cpp {cast-overload-for-arg} {other} + + \sa QSharedPointer::staticCast(), qSharedPointerDynamicCast(), qSharedPointerConstCast() +*/ + /*! \fn template QSharedPointer qSharedPointerCast(const QWeakPointer &other) \relates QSharedPointer @@ -1231,6 +1298,17 @@ \sa QSharedPointer::dynamicCast(), qSharedPointerCast(), qSharedPointerConstCast() */ +/*! + \fn template QSharedPointer qSharedPointerDynamicCast(QSharedPointer &&src) + \relates QSharedPointer + \since 6.9 + \overload qSharedPointerDynamicCast(const QSharedPointer &src) + + \include qsharedpointer.cpp {cast-overload-for-arg} {src} + + \sa QSharedPointer::dynamicCast(), qSharedPointerCast(), qSharedPointerConstCast() +*/ + /*! \fn template QSharedPointer qSharedPointerDynamicCast(const QWeakPointer &src) \relates QSharedPointer @@ -1265,6 +1343,17 @@ \sa QSharedPointer::constCast(), qSharedPointerCast(), qSharedPointerDynamicCast() */ +/*! + \fn template QSharedPointer qSharedPointerConstCast(QSharedPointer &&src) + \relates QSharedPointer + \since 6.9 + \overload qSharedPointerConstCast(const QSharedPointer &src) + + \include qsharedpointer.cpp {cast-overload-for-arg} {src} + + \sa QSharedPointer::constCast(), qSharedPointerCast(), qSharedPointerDynamicCast() +*/ + /*! \fn template QSharedPointer qSharedPointerConstCast(const QWeakPointer &src) \relates QSharedPointer @@ -1302,6 +1391,17 @@ \sa QSharedPointer::objectCast(), qSharedPointerCast(), qSharedPointerConstCast() */ +/*! + \fn template QSharedPointer qSharedPointerObjectCast(QSharedPointer &&src) + \relates QSharedPointer + \since 6.9 + \overload qSharedPointerObjectCast(const QSharedPointer &src) + + \include qsharedpointer.cpp {cast-overload-for-arg} {src} + + \sa QSharedPointer::objectCast(), qSharedPointerCast(), qSharedPointerConstCast() +*/ + /*! \fn template std::shared_ptr qSharedPointerObjectCast(const std::shared_ptr &src) \relates QSharedPointer diff --git a/src/corelib/tools/qsharedpointer.h b/src/corelib/tools/qsharedpointer.h index 116c9afa00c..0524ddca203 100644 --- a/src/corelib/tools/qsharedpointer.h +++ b/src/corelib/tools/qsharedpointer.h @@ -65,10 +65,14 @@ public: void reset(T *t, Deleter deleter); // casts: - template QSharedPointer staticCast() const; - template QSharedPointer dynamicCast() const; - template QSharedPointer constCast() const; - template QSharedPointer objectCast() const; + template QSharedPointer staticCast() const &; + template QSharedPointer staticCast() &&; + template QSharedPointer dynamicCast() const &; + template QSharedPointer dynamicCast() &&; + template QSharedPointer constCast() const &; + template QSharedPointer constCast() &&; + template QSharedPointer objectCast() const &; + template QSharedPointer objectCast() &&; template static inline QSharedPointer create(Args &&... args); @@ -164,12 +168,16 @@ template bool operator==(std::nullptr_t, const QWeakPointer &rhs); template bool operator!=(std::nullptr_t, const QWeakPointer &rhs); template QSharedPointer qSharedPointerCast(const QSharedPointer &other); +template QSharedPointer qSharedPointerCast(QSharedPointer &&other); template QSharedPointer qSharedPointerCast(const QWeakPointer &other); template QSharedPointer qSharedPointerDynamicCast(const QSharedPointer &src); +template QSharedPointer qSharedPointerDynamicCast(QSharedPointer &&src); template QSharedPointer qSharedPointerDynamicCast(const QWeakPointer &src); template QSharedPointer qSharedPointerConstCast(const QSharedPointer &src); +template QSharedPointer qSharedPointerConstCast(QSharedPointer &&src); template QSharedPointer qSharedPointerConstCast(const QWeakPointer &src); template QSharedPointer qSharedPointerObjectCast(const QSharedPointer &src); +template QSharedPointer qSharedPointerObjectCast(QSharedPointer &&src); template QSharedPointer qSharedPointerObjectCast(const QWeakPointer &src); template std::shared_ptr qobject_pointer_cast(const std::shared_ptr &src); template std::shared_ptr qobject_pointer_cast(std::shared_ptr &&src);