Doc: Fix documentation warnings for Qt Core

- QCborError: Classes cannot relate to header files; use \inheaderfile
  instead and link to the class from header file documentation.

- QRecursiveMutex: QDoc doesn't allow shared documentation comments
  for duplicating \fn docs between the base and deriving classes.
  Remove the sharing, the function documentation is available under
  'All Members' doc for QRecursiveMutex.

- QMultiMap: unite() and one overload of insert() were not recognized
  because their definitions in the same header file interfered with
  QDoc - use Q_CLANG_QDOC macro to comment them out, and tag \fn
  comments to ensure that the function documentation is matched.

Change-Id: Ic96869904a72d92453e4ffa6901000147571969b
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

9 files changed, 21 insertions, 20 deletions

diff --git a/src/corelib/global/qnamespace.qdoc b/src/corelib/global/qnamespace.qdoc
index 708ecb11ab..cfa86888b2 100644
--- a/src/corelib/global/qnamespace.qdoc
+++ b/src/corelib/global/qnamespace.qdoc
@@ -3339,6 +3339,8 @@
 
   This is a dummy type, designed to help users transition from certain deprecated APIs to their replacement APIs.
 
+  \omitvalue ReturnByValue
+
   \sa QCursor::bitmap()
   \sa QCursor::mask()
   \sa QLabel::picture()
diff --git a/src/corelib/kernel/qmetatype.cpp b/src/corelib/kernel/qmetatype.cpp
index a2b7fec5cd..71eec11e01 100644
--- a/src/corelib/kernel/qmetatype.cpp
+++ b/src/corelib/kernel/qmetatype.cpp
@@ -523,7 +523,7 @@ struct DefinedTypesFilter {
     as the QMetaType \a b, otherwise returns \c false.
 */
 
-/*! \fn bool operator!=(const QMetaType &a, const QMetaType &c)
+/*! \fn bool operator!=(const QMetaType &a, const QMetaType &b)
     \since 5.15
     \relates QMetaType
     \overload
diff --git a/src/corelib/serialization/qcborcommon.cpp b/src/corelib/serialization/qcborcommon.cpp
index 37fb198744..5fc47fa399 100644
--- a/src/corelib/serialization/qcborcommon.cpp
+++ b/src/corelib/serialization/qcborcommon.cpp
@@ -54,6 +54,8 @@ QT_BEGIN_NAMESPACE
    \brief The <QtCborCommon> header contains definitions common to both the
    streaming classes (QCborStreamReader and QCborStreamWriter) and to
    QCborValue.
+
+   \sa QCborError
  */
 
 /*!
@@ -203,7 +205,7 @@ QDataStream &operator>>(QDataStream &ds, QCborSimpleType &st)
 /*!
    \class QCborError
    \inmodule QtCore
-   \relates <QtCborCommon>
+   \inheaderfile <QtCborCommon>
    \reentrant
    \since 5.12
 
diff --git a/src/corelib/text/qstringview.cpp b/src/corelib/text/qstringview.cpp
index c4ddb06ea4..08dade7e68 100644
--- a/src/corelib/text/qstringview.cpp
+++ b/src/corelib/text/qstringview.cpp
@@ -528,9 +528,9 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QString QStringView::arg(Args &&...args) const
-    \fn QString QLatin1String::arg(Args &&...args) const
-    \fn QString QString::arg(Args &&...args) const
+    \fn template <typename...Args> QString QStringView::arg(Args &&...args) const
+    \fn template <typename...Args> QString QLatin1String::arg(Args &&...args) const
+    \fn template <typename...Args> QString QString::arg(Args &&...args) const
     \since 5.14
 
     Replaces occurrences of \c{%N} in this string with the corresponding
diff --git a/src/corelib/thread/qmutex.cpp b/src/corelib/thread/qmutex.cpp
index 0508932d68..9bfd50f2d9 100644
--- a/src/corelib/thread/qmutex.cpp
+++ b/src/corelib/thread/qmutex.cpp
@@ -212,7 +212,6 @@ QMutex::~QMutex()
 }
 
 /*! \fn void QMutex::lock()
-    \fn QRecursiveMutex::lock()
 
     Locks the mutex. If another thread has locked the mutex then this
     call will block until that thread has unlocked it.
@@ -237,7 +236,6 @@ void QMutex::lock() QT_MUTEX_LOCK_NOEXCEPT
 }
 
 /*! \fn bool QMutex::tryLock(int timeout)
-    \fn bool QRecursiveMutex::tryLock(int timeout)
 
     Attempts to lock the mutex. This function returns \c true if the lock
     was obtained; otherwise it returns \c false. If another thread has
@@ -272,7 +270,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT
 }
 
 /*! \fn bool QMutex::try_lock()
-    \fn bool QRecursiveMutex::try_lock()
     \since 5.8
 
     Attempts to lock the mutex. This function returns \c true if the lock
@@ -286,7 +283,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT
 */
 
 /*! \fn template <class Rep, class Period> bool QMutex::try_lock_for(std::chrono::duration<Rep, Period> duration)
-    \fn template <class Rep, class Period> bool QRecursiveMutex::try_lock_for(std::chrono::duration<Rep, Period> duration)
     \since 5.8
 
     Attempts to lock the mutex. This function returns \c true if the lock
@@ -311,7 +307,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT
 */
 
 /*! \fn template<class Clock, class Duration> bool QMutex::try_lock_until(std::chrono::time_point<Clock, Duration> timePoint)
-    \fn template<class Clock, class Duration> bool QRecursiveMutex::try_lock_until(std::chrono::time_point<Clock, Duration> timePoint)
     \since 5.8
 
     Attempts to lock the mutex. This function returns \c true if the lock
@@ -336,7 +331,6 @@ bool QMutex::tryLock(int timeout) QT_MUTEX_LOCK_NOEXCEPT
 */
 
 /*! \fn void QMutex::unlock()
-    \fn void QRecursiveMutex::unlock()
 
     Unlocks the mutex. Attempting to unlock a mutex in a different
     thread to the one that locked it results in an error. Unlocking a
diff --git a/src/corelib/time/qdatetime.cpp b/src/corelib/time/qdatetime.cpp
index 45c6ecbf23..86c08058fc 100644
--- a/src/corelib/time/qdatetime.cpp
+++ b/src/corelib/time/qdatetime.cpp
@@ -1127,9 +1127,7 @@ static QString toStringIsoDate(QDate date)
     \overload
 
     Returns the date as a string. The \a format parameter determines the format
-    of the string. If \a cal is supplied, it determines the calendar used to
-    represent the date; it defaults to Gregorian and only affects the
-    locale-specific formats.
+    of the string.
 
     If the \a format is Qt::TextDate, the string is formatted in the default
     way. The day and month names will be localized names using the system
@@ -1236,7 +1234,7 @@ QT_WARNING_POP
     \fn QString QDate::toString(QStringView format, QCalendar cal) const
 
     Returns the date as a string. The \a format parameter determines the format
-    of the result string. If \cal is supplied, it determines the calendar used
+    of the result string. If \a cal is supplied, it determines the calendar used
     to represent the date; it defaults to Gregorian.
 
     These expressions may be used:
@@ -4437,7 +4435,7 @@ QT_WARNING_POP
     \fn QString QDateTime::toString(QStringView format, QCalendar cal) const
 
     Returns the datetime as a string. The \a format parameter determines the
-    format of the result string. If \cal is supplied, it determines the calendar
+    format of the result string. If \a cal is supplied, it determines the calendar
     used to represent the date; it defaults to Gregorian. See QTime::toString()
     and QDate::toString() for the supported specifiers for time and date,
     respectively.
diff --git a/src/corelib/tools/qmap.cpp b/src/corelib/tools/qmap.cpp
index 9b9c67e42b..6d2b8f7a3e 100644
--- a/src/corelib/tools/qmap.cpp
+++ b/src/corelib/tools/qmap.cpp
@@ -1999,7 +1999,7 @@ void QMapDataBase::freeData(QMapDataBase *d)
     \sa replace()
 */
 
-/*! \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insert(typename QMultiMap<Key, T>::const_iterator pos, const Key &key, const T &value)
+/*! \fn [qmultimap-insert-pos] template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::insert(typename QMultiMap<Key, T>::const_iterator pos, const Key &key, const T &value)
 
     \since 5.1
     Inserts a new item with the key \a key and value \a value and with hint \a pos
@@ -2128,7 +2128,8 @@ void QMapDataBase::freeData(QMapDataBase *d)
     once in the returned list.
 */
 
-/*! \fn template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Key, T> &other)
+/*!
+    \fn [qmultimap-unite] template <class Key, class T> QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Key, T> &other)
 
     Inserts all the items in the \a other map into this map. If a
     key is common to both maps, the resulting map will contain the
diff --git a/src/corelib/tools/qmap.h b/src/corelib/tools/qmap.h
index 2abdc5e60e..427a4ad5a0 100644
--- a/src/corelib/tools/qmap.h
+++ b/src/corelib/tools/qmap.h
@@ -1115,9 +1115,11 @@ public:
     inline typename QMap<Key, T>::iterator replace(const Key &key, const T &value)
     { return QMap<Key, T>::insert(key, value); }
     typename QMap<Key, T>::iterator insert(const Key &key, const T &value);
+    //! [qmultimap-insert-pos]
     typename QMap<Key, T>::iterator insert(typename QMap<Key, T>::const_iterator pos,
-                                           const Key &keyi, const T &value);
+                                           const Key &key, const T &value);
 
+    //! [qmultimap-unite]
     QMultiMap &unite(const QMultiMap &other);
     inline QMultiMap &operator+=(const QMultiMap &other)
     { return unite(other); }
@@ -1222,6 +1224,7 @@ Q_INLINE_TEMPLATE typename QMap<Key, T>::iterator QMultiMap<Key, T>::insert(cons
     return typename QMap<Key, T>::iterator(z);
 }
 
+#ifndef Q_CLANG_QDOC
 template <class Key, class T>
 typename QMap<Key, T>::iterator QMultiMap<Key, T>::insert(typename QMap<Key, T>::const_iterator pos,
                                                           const Key &akey, const T &avalue)
@@ -1287,6 +1290,7 @@ Q_INLINE_TEMPLATE QMultiMap<Key, T> &QMultiMap<Key, T>::unite(const QMultiMap<Ke
     }
     return *this;
 }
+#endif // Q_CLANG_QDOC
 
 template <class Key, class T>
 Q_INLINE_TEMPLATE bool QMultiMap<Key, T>::contains(const Key &key, const T &value) const
diff --git a/src/corelib/tools/qvarlengtharray.qdoc b/src/corelib/tools/qvarlengtharray.qdoc
index e5ba47b8ef..3dab41dd22 100644
--- a/src/corelib/tools/qvarlengtharray.qdoc
+++ b/src/corelib/tools/qvarlengtharray.qdoc
@@ -904,7 +904,7 @@
 */
 
 /*!
-    template <typename T, int Prealloc> uint qHash(const QVarLengthArray<T, Prealloc> &key, uint seed = 0)
+    \fn template <typename T, int Prealloc> uint qHash(const QVarLengthArray<T, Prealloc> &key, uint seed = 0)
     \relates QVarLengthArray
     \since 5.14