From a2c8184b6b241b063e9af005edf082e653dfd8a6 Mon Sep 17 00:00:00 2001 From: Nico Vertriest Date: Tue, 1 Jun 2021 11:38:06 +0200 Subject: [PATCH] Doc: Ensure deprecated APIs in Qt Core are documented as such Added \deprecated [version_since] when needed Remove references to deprecated functions in \sa statements Fixes: QTBUG-94534 Pick-to: 6.2 Change-Id: I3b3d4277d63fc5d6d207c28ff2484aed30b83247 Reviewed-by: Edward Welbourne --- src/corelib/global/qlibraryinfo.cpp | 3 +-- src/corelib/kernel/qjnienvironment.cpp | 7 ++---- src/corelib/kernel/qvariant.cpp | 20 +++++++-------- src/corelib/text/qlocale.cpp | 34 +++++++++++++------------- src/corelib/text/qstring.cpp | 8 ++---- src/corelib/thread/qfuture.qdoc | 18 ++++++-------- src/corelib/thread/qfuturewatcher.cpp | 20 ++++++--------- src/corelib/time/qtimezone.cpp | 2 +- src/corelib/tools/qhash.cpp | 8 +++--- src/corelib/tools/qscopedpointer.cpp | 6 ++--- 10 files changed, 55 insertions(+), 71 deletions(-) diff --git a/src/corelib/global/qlibraryinfo.cpp b/src/corelib/global/qlibraryinfo.cpp index 740e32635f..625fab75f7 100644 --- a/src/corelib/global/qlibraryinfo.cpp +++ b/src/corelib/global/qlibraryinfo.cpp @@ -531,10 +531,9 @@ void QLibraryInfoPrivate::keyAndDefault(QLibraryInfo::LibraryPath loc, QString * } /*! \fn QString QLibraryInfo::location(LibraryLocation loc) - \deprecated Use path() instead. + \deprecated [6.0] Use path() instead. Returns the path specified by \a loc. - \sa path() */ /*! diff --git a/src/corelib/kernel/qjnienvironment.cpp b/src/corelib/kernel/qjnienvironment.cpp index 8982d6712f..a72078d2cf 100644 --- a/src/corelib/kernel/qjnienvironment.cpp +++ b/src/corelib/kernel/qjnienvironment.cpp @@ -323,8 +323,6 @@ JavaVM *QJniEnvironment::javaVM() } /*! - \fn bool QJniEnvironment::registerNativeMethods(const char *className, const JNINativeMethod methods[], int size) - Registers the Java methods in the array \a methods of size \a size, each of which can call native C++ functions from class \a className. These methods must be registered before any attempt to call them. @@ -355,10 +353,10 @@ bool QJniEnvironment::registerNativeMethods(const char *className, const JNINati return false; return registerNativeMethods(classObject.objectClass(), methods, size); } - +#if QT_DEPRECATED_SINCE(6, 2) /*! \overload - \obsolete Use the overload with a const JNINativeMethod[] instead. + \deprecated [6.2] Use the overload with a const JNINativeMethod[] instead. Registers the Java methods in the array \a methods of size \a size, each of which can call native C++ functions from class \a className. These methods @@ -380,7 +378,6 @@ bool QJniEnvironment::registerNativeMethods(const char *className, const JNINati env.registerNativeMethods("org/qtproject/android/TestJavaClass", methods, 2); \endcode */ -#if QT_DEPRECATED_SINCE(6, 2) bool QJniEnvironment::registerNativeMethods(const char *className, JNINativeMethod methods[], int size) { diff --git a/src/corelib/kernel/qvariant.cpp b/src/corelib/kernel/qvariant.cpp index c16e669c2c..5cf8636dcd 100644 --- a/src/corelib/kernel/qvariant.cpp +++ b/src/corelib/kernel/qvariant.cpp @@ -378,7 +378,7 @@ static void customClear(QVariant::Private *d) */ /*! - \deprecated Use QMetaType::Type instead. + \deprecated Use \l QMetaType::Type instead. \enum QVariant::Type This enum type defines the types of variable that a QVariant can @@ -795,7 +795,7 @@ QVariant::QVariant(const QVariant &p) */ /*! \fn QVariant::QVariant(Type type) - \deprecated + \deprecated [6.0] Use the constructor taking a QMetaType instead. Constructs an uninitialized variant of type \a type. This will create a variant in a special null state that if accessed will return a default @@ -951,7 +951,7 @@ QVariant::QVariant(const QPersistentModelIndex &modelIndex) #endif /*! \fn QVariant::Type QVariant::type() const - \deprecated + \deprecated [6.0] Use typeId() or metaType() instead. Returns the storage type of the value stored in the variant. Although this function is declared as returning QVariant::Type, @@ -1088,7 +1088,7 @@ void QVariant::clear() /*! \fn const char *QVariant::typeToName(int typeId) - \deprecated Use QMetaType instead + \deprecated [6.0] Use \c QMetaType(typeId).name() instead. Converts the int representation of the storage type, \a typeId, to its string representation. @@ -1098,7 +1098,7 @@ void QVariant::clear() /*! \fn QVariant::Type QVariant::nameToType(const char *name) - \deprecated Use QMetaType instead + \deprecated [6.0] Use \c QMetaType.fromName(name).id() instead Converts the string representation of the storage type given in \a name, to its enum representation. @@ -1360,13 +1360,13 @@ QDataStream &operator<<(QDataStream &s, const QVariant &p) } /*! \fn QDataStream& operator>>(QDataStream &s, QVariant::Type &p) - \deprecated + \deprecated [6.0] Stream QMetaType::Type instead. Reads a variant type \a p in enum representation from the stream \a s. */ /*! \fn QDataStream& operator<<(QDataStream &s, const QVariant::Type p) - \deprecated + \deprecated [6.0] Stream QMetaType::Type instead. Writes a variant type \a p to the stream \a s. */ @@ -1980,7 +1980,7 @@ QVariantList QVariant::toList() const /*! \fn bool QVariant::canConvert(int targetTypeId) const \overload - \deprecated + \deprecated [6.0] Use \c canConvert(QMetaType(targetTypeId)) instead. \sa QMetaType::canConvert() */ @@ -1999,7 +1999,7 @@ QVariantList QVariant::toList() const /*! \fn bool QVariant::convert(int targetTypeId) - \deprecated + \deprecated [6.0] Use \c convert(QMetaType(targetTypeId)) instead. Casts the variant to the requested type, \a targetTypeId. If the cast cannot be done, the variant is still changed to the requested type, but is left in a cleared @@ -2017,7 +2017,7 @@ QVariantList QVariant::toList() const failed a previous conversion will always fail, changing the type, remaining null, and returning \c false. - \sa canConvert(int targetTypeId), clear() + \sa canConvert(), clear() */ /*! diff --git a/src/corelib/text/qlocale.cpp b/src/corelib/text/qlocale.cpp index c2c0546643..c7cecce37f 100644 --- a/src/corelib/text/qlocale.cpp +++ b/src/corelib/text/qlocale.cpp @@ -1211,7 +1211,7 @@ void QLocale::setDefault(const QLocale &locale) /*! Returns the language of this locale. - \sa script(), country(), languageToString(), bcp47Name() + \sa script(), territory(), languageToString(), bcp47Name() */ QLocale::Language QLocale::language() const { @@ -1223,7 +1223,7 @@ QLocale::Language QLocale::language() const Returns the script of this locale. - \sa language(), country(), languageToString(), scriptToString(), bcp47Name() + \sa language(), territory(), languageToString(), scriptToString(), bcp47Name() */ QLocale::Script QLocale::script() const { @@ -1244,7 +1244,7 @@ QLocale::Territory QLocale::territory() const #if QT_DEPRECATED_SINCE(6, 6) /*! - \deprecated Use territory() instead. + \deprecated [6.6] Use \l territory() instead. Returns the territory of this locale. @@ -1263,10 +1263,10 @@ QLocale::Country QLocale::country() const and country is an uppercase, two- or three-letter ISO 3166 country code. Note that even if QLocale object was constructed with an explicit script, - name() will not contain it for compatibility reasons. Use bcp47Name() instead + name() will not contain it for compatibility reasons. Use \l bcp47Name() instead if you need a full locale name. - \sa QLocale(), language(), script(), country(), bcp47Name() + \sa QLocale(), language(), script(), territory(), bcp47Name() */ QString QLocale::name() const @@ -1323,7 +1323,7 @@ T toIntegral_helper(const QLocalePrivate *d, QStringView str, bool *ok) This function tries to conform the locale name to BCP47. - \sa language(), country(), script(), uiLanguages() + \sa language(), territory(), script(), uiLanguages() */ QString QLocale::bcp47Name() const { @@ -1338,7 +1338,7 @@ QString QLocale::bcp47Name() const For \c QLocale::AnyLanguage an empty string is returned. \since 6.1 - \sa codeToLanguage(), language(), name(), bcp47Name(), countryToCode(), scriptToCode() + \sa codeToLanguage(), language(), name(), bcp47Name(), territoryToCode(), scriptToCode() */ QString QLocale::languageToCode(Language language) { @@ -1352,7 +1352,7 @@ QString QLocale::languageToCode(Language language) If the code is invalid or not known QLocale::AnyLanguage is returned. \since 6.1 - \sa languageToCode(), codeToCountry(), codeToScript() + \sa languageToCode(), codeToTerritory(), codeToScript() */ QLocale::Language QLocale::codeToLanguage(QStringView languageCode) noexcept { @@ -1391,7 +1391,7 @@ QLocale::Territory QLocale::codeToTerritory(QStringView territoryCode) noexcept #if QT_DEPRECATED_SINCE(6, 6) /*! - \deprecated Use territoryToCode(Territory) instead. + \deprecated [6.6] Use \l territoryToCode() instead. Returns the two-letter territory code for \a country, as defined in the ISO 3166 standard. @@ -1411,7 +1411,7 @@ QString QLocale::countryToCode(Country country) If the code is invalid or not known QLocale::AnyTerritory is returned. - \deprecated Use codeToTerritory(QStringView) instead. + \deprecated [6.6] Use codeToTerritory(QStringView) instead. \since 6.1 \sa territoryToCode(), codeToLanguage(), codeToScript() */ @@ -1428,7 +1428,7 @@ QLocale::Country QLocale::codeToCountry(QStringView countryCode) noexcept \note For \c{QLocale::AnyScript} an empty string is returned. \since 6.1 - \sa script(), name(), bcp47Name(), languageToCode(), countryToCode() + \sa script(), name(), bcp47Name(), languageToCode(), territoryToCode() */ QString QLocale::scriptToCode(Script script) { @@ -1442,7 +1442,7 @@ QString QLocale::scriptToCode(Script script) If the code is invalid or not known QLocale::AnyScript is returned. \since 6.1 - \sa scriptToCode(), codeToLanguage(), codeToCountry() + \sa scriptToCode(), codeToLanguage(), codeToTerritory() */ QLocale::Script QLocale::codeToScript(QStringView scriptCode) noexcept { @@ -1452,7 +1452,7 @@ QLocale::Script QLocale::codeToScript(QStringView scriptCode) noexcept /*! Returns a QString containing the name of \a language. - \sa countryToString(), scriptToString(), bcp47Name() + \sa territoryToString(), scriptToString(), bcp47Name() */ QString QLocale::languageToString(Language language) @@ -1478,7 +1478,7 @@ QString QLocale::territoryToString(QLocale::Territory territory) #if QT_DEPRECATED_SINCE(6, 6) /*! - \deprecated Use territoryToString(Territory) instead. + \deprecated [6.6] Use \l territoryToString() instead. Returns a QString containing the name of \a country. @@ -1495,7 +1495,7 @@ QString QLocale::countryToString(Country country) Returns a QString containing the name of \a script. - \sa languageToString(), countryToString(), script(), bcp47Name() + \sa languageToString(), territoryToString(), script(), bcp47Name() */ QString QLocale::scriptToString(QLocale::Script script) { @@ -2639,7 +2639,7 @@ QList QLocale::matchingLocales(QLocale::Language language, QLocale::Scr #if QT_DEPRECATED_SINCE(6, 6) /*! - \deprecated Use matchingLocales() instead and consult the territory() of each. + \deprecated [6.6] Use \l matchingLocales() instead and consult the \l territory() of each. \since 4.3 Returns the list of countries that have entries for \a language in Qt's locale @@ -4379,7 +4379,7 @@ QString QLocale::nativeTerritoryName() const #if QT_DEPRECATED_SINCE(6, 6) /*! - \deprecated Use nativeTerritoryName() instead. + \deprecated [6.6] Use \l nativeTerritoryName() instead. \since 4.8 Returns a native name of the territory for the locale. For example diff --git a/src/corelib/text/qstring.cpp b/src/corelib/text/qstring.cpp index 6badf9b5c1..99534cb3d1 100644 --- a/src/corelib/text/qstring.cpp +++ b/src/corelib/text/qstring.cpp @@ -5399,17 +5399,13 @@ QString QString::fromUtf16(const char16_t *unicode, qsizetype size) /*! \fn QString QString::fromUtf16(const ushort *str, qsizetype size) - \deprecated - - Use the \c char16_t overload. + \deprecated [6.0] Use the \c char16_t overload instead. */ /*! \fn QString QString::fromUcs4(const uint *str, qsizetype size) \since 4.2 - \deprecated - - Use the \c char32_t overload instead. + \deprecated [6.0] Use the \c char32_t overload instead. */ /*! diff --git a/src/corelib/thread/qfuture.qdoc b/src/corelib/thread/qfuture.qdoc index 25cbfe18c9..0359140a9c 100644 --- a/src/corelib/thread/qfuture.qdoc +++ b/src/corelib/thread/qfuture.qdoc @@ -199,8 +199,7 @@ #if QT_DEPRECATED_SINCE(6, 0) /*! \fn template void QFuture::setPaused(bool paused) - \deprecated - Use setSuspended() instead. + \deprecated [6.0] Use setSuspended() instead. If \a paused is true, this function pauses the asynchronous computation represented by the future. If the computation is already paused, this @@ -216,13 +215,12 @@ returned by QtConcurrent::run() cannot be paused; but the future returned by QtConcurrent::mappedReduced() can. - \sa pause(), resume(), togglePaused() + \sa suspend(), resume(), toggleSuspended() */ /*! \fn template bool QFuture::isPaused() const - \deprecated - Use isSuspending() or isSuspended() instead. + \deprecated [6.0] Use isSuspending() or isSuspended() instead. Returns \c true if the asynchronous computation has been paused with the pause() function; otherwise returns \c false. @@ -231,13 +229,12 @@ function returns \c true. See setPaused() for more details. To check if pause actually took effect, use isSuspended() instead. - \sa setPaused(), togglePaused(), isSuspended() + \sa toggleSuspended(), isSuspended() */ /*! \fn template void QFuture::pause() - \deprecated - Use suspend() instead. + \deprecated [6.0] Use suspend() instead. Pauses the asynchronous computation represented by this future. This is a convenience method that simply calls setPaused(true). @@ -247,15 +244,14 @@ /*! \fn template void QFuture::togglePaused() - \deprecated - Use toggleSuspended() instead. + \deprecated [6.0] Use toggleSuspended() instead. Toggles the paused state of the asynchronous computation. In other words, if the computation is currently paused, calling this function resumes it; if the computation is running, it is paused. This is a convenience method for calling setPaused(!isPaused()). - \sa setPaused(), pause(), resume() + \sa setSuspended(), suspend(), resume() */ #endif // QT_DEPRECATED_SINCE(6, 0) diff --git a/src/corelib/thread/qfuturewatcher.cpp b/src/corelib/thread/qfuturewatcher.cpp index be32345081..75d9a73147 100644 --- a/src/corelib/thread/qfuturewatcher.cpp +++ b/src/corelib/thread/qfuturewatcher.cpp @@ -136,8 +136,7 @@ void QFutureWatcherBase::cancel() #if QT_DEPRECATED_SINCE(6, 0) /*! \fn template void QFutureWatcher::setPaused(bool paused) - \deprecated - Use setSuspended() instead. + \deprecated [6.6] Use setSuspended() instead. If \a paused is true, this function pauses the asynchronous computation represented by the future(). If the computation is already paused, this @@ -154,7 +153,7 @@ void QFutureWatcherBase::cancel() QFuture returned by QtConcurrent::run() cannot be paused; but the QFuture returned by QtConcurrent::mappedReduced() can. - \sa pause(), resume(), togglePaused() + \sa suspend(), resume(), toggleSuspended() */ void QFutureWatcherBase::setPaused(bool paused) { @@ -233,15 +232,14 @@ void QFutureWatcherBase::resume() #if QT_DEPRECATED_SINCE(6, 0) /*! \fn template void QFutureWatcher::togglePaused() - \deprecated - Use toggleSuspended() instead. + \deprecated [6.0] Use toggleSuspended() instead. Toggles the paused state of the asynchronous computation. In other words, if the computation is currently paused, calling this function resumes it; if the computation is running, it is paused. This is a convenience method for calling setPaused(!isPaused()). - \sa setPaused(), pause(), resume() + \sa setSuspended(), suspend(), resume() */ void QFutureWatcherBase::togglePaused() { @@ -359,8 +357,7 @@ bool QFutureWatcherBase::isCanceled() const /*! \fn template bool QFutureWatcher::isPaused() const - \deprecated - Use isSuspending() or isSuspended() instead. + \deprecated [6.0] Use isSuspending() or isSuspended() instead. Returns \c true if the asynchronous computation has been paused with the pause() function; otherwise returns \c false. @@ -369,7 +366,7 @@ bool QFutureWatcherBase::isCanceled() const function returns \c true. See setPaused() for more details. To check if pause actually took effect, use isSuspended() instead. - \sa setPaused(), togglePaused(), isSuspended() + \sa setSuspended(), toggleSuspended(), isSuspended() */ bool QFutureWatcherBase::isPaused() const @@ -661,8 +658,7 @@ QT_WARNING_POP #if QT_DEPRECATED_SINCE(6, 0) /*! \fn template void QFutureWatcher::paused() - \deprecated - Use suspending() instead. + \deprecated [6.0] Use suspending() instead. This signal is emitted when the state of the watched future is set to paused. @@ -673,7 +669,7 @@ QT_WARNING_POP still be delivered. To to be informed when pause() actually took effect, use the suspended() signal. - \sa setPaused(), pause(), suspended() + \sa setSuspended(), suspend(), suspended() */ #endif // QT_DEPRECATED_SINCE(6, 0) diff --git a/src/corelib/time/qtimezone.cpp b/src/corelib/time/qtimezone.cpp index 1aad2a3f06..f84b98e670 100644 --- a/src/corelib/time/qtimezone.cpp +++ b/src/corelib/time/qtimezone.cpp @@ -502,7 +502,7 @@ QLocale::Territory QTimeZone::territory() const #if QT_DEPRECATED_SINCE(6, 6) /*! - \deprecated Use territory() instead. + \deprecated [6.6] Use territory() instead. Returns the territory for the time zone. */ diff --git a/src/corelib/tools/qhash.cpp b/src/corelib/tools/qhash.cpp index 38c3f9cef6..fe3d8d912e 100644 --- a/src/corelib/tools/qhash.cpp +++ b/src/corelib/tools/qhash.cpp @@ -877,14 +877,14 @@ void QHashSeed::resetRandomGlobalSeed() #if QT_DEPRECATED_SINCE(6,6) /*! \relates QHash \since 5.6 - \deprecated Use QHashSeed::globalSeed() instead. + \deprecated [6.6] Use QHashSeed::globalSeed() instead. Returns the current global QHash seed. The seed is set in any newly created QHash. See \l{qHash} about how this seed is being used by QHash. - \sa qSetGlobalQHashSeed, QHashSeed::globalSeed() + \sa QHashSeed, QHashSeed::globalSeed() */ int qGlobalQHashSeed() { @@ -893,7 +893,7 @@ int qGlobalQHashSeed() /*! \relates QHash \since 5.6 - \deprecated Use QHashSeed instead. + \deprecated [6.6] Use QHashSeed instead. Sets the global QHash seed to \a newSeed. @@ -913,7 +913,7 @@ int qGlobalQHashSeed() If the environment variable \c QT_HASH_SEED is set, calling this function will result in a no-op. - \sa qGlobalQHashSeed, QHashSeed + \sa qHashSeed::globalSeed, QHashSeed */ void qSetGlobalQHashSeed(int newSeed) { diff --git a/src/corelib/tools/qscopedpointer.cpp b/src/corelib/tools/qscopedpointer.cpp index 8146fe33cf..1844013d46 100644 --- a/src/corelib/tools/qscopedpointer.cpp +++ b/src/corelib/tools/qscopedpointer.cpp @@ -248,7 +248,7 @@ QT_BEGIN_NAMESPACE /*! \fn template T *QScopedPointer::take() - \deprecated Use std::unique_ptr and release() instead. + \deprecated [6.1] Use \c std::unique_ptr and \c release() instead. Returns the value of the pointer referenced by this object. The pointer of this QScopedPointer object will be reset to \nullptr. @@ -265,7 +265,7 @@ QT_BEGIN_NAMESPACE /*! \fn template void QScopedPointer::swap(QScopedPointer &lhs, QScopedPointer &rhs) - \deprecated Use std::unique_ptr instead; this function may let a pointer + \deprecated [6.1] Use \c std::unique_ptr instead; this function may let a pointer escape its scope. Swaps \a lhs with \a rhs. @@ -335,7 +335,7 @@ QT_BEGIN_NAMESPACE /*! \fn template void QScopedArrayPointer::swap(QScopedArrayPointer &other) - \deprecated Use std::unique_ptr instead; this function may let a pointer + \deprecated [6.1] Use \c std::unique_ptr instead; this function may let a pointer escape its scope. Swap this pointer with \a other.