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>

3 files changed, 9 insertions, 4 deletions

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