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
Change-Id: I3b3d4277d63fc5d6d207c28ff2484aed30b83247
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>
(cherry picked from commit a2c8184b6b241b063e9af005edf082e653dfd8a6)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

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 0c58d0b314..dcba73731c 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> 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 b68877b517..619a03a013 100644
--- a/src/corelib/text/qstring.cpp
+++ b/src/corelib/text/qstring.cpp
@@ -5395,17 +5395,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 <typename T> void QFuture<T>::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 <typename T> bool QFuture<T>::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 <typename T> void QFuture<T>::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 <typename T> void QFuture<T>::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 <typename T> void QFutureWatcher<T>::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 <typename T> void QFutureWatcher<T>::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 <typename T> bool QFutureWatcher<T>::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 <typename T> void QFutureWatcher<T>::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 <typename T, typename Cleanup> T *QScopedPointer<T, Cleanup>::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 <typename T, typename Cleanup> void QScopedPointer<T, Cleanup>::swap(QScopedPointer<T, Cleanup> &lhs, QScopedPointer<T, Cleanup> &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 <typename T, typename Cleanup> void QScopedArrayPointer<T, Cleanup>::swap(QScopedArrayPointer<T, Cleanup> &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.