Doc: Fix documentation issues for Qt Core

* Tag deprecated Q(Multi)Map operators in the header to correctly
  match them with documentation \fn commands.
* Add documentation for QByteArrayView comparison operators.
* Add a dummy typedef 'jfieldID' for generating docs correctly
  on non-Android platforms
* Fix other minor issues

Pick-to: 6.2
Task-number: QTBUG-95860
Change-Id: I141d2f75d6aa10557aa374201f09ad74b4cd6e81
Reviewed-by: Paul Wicking <[email protected]>

src/corelib/doc/include/jni.h

@@ -60,5 +60,6 @@ struct _jobject;
 typedef _jobject* jobject;
 typedef int jint;
 typedef int jmethodID;
+typedef int jfieldID;
 typedef void* JavaVM;
 #endif

src/corelib/global/qglobal.cpp

@@ -353,7 +353,7 @@ static_assert(sizeof(qint64) == 8, "Internal error, qint64 is misdefined");
 /*!
     \fn template <typename Enum> QFlags &QFlags<Enum>::operator=(const QFlags &other)
 
-    Assigns \a other to this object and returns a reference to this
+    Assigns \e other to this object and returns a reference to this
     object.
 */
 

src/corelib/io/qprocess_win.cpp

@@ -824,6 +824,7 @@ void QProcessPrivate::findExitCode()
 }
 
 /*! \reimp
+    \internal
 */
 qint64 QProcess::writeData(const char *data, qint64 len)
 {

src/corelib/kernel/qproperty.cpp

@@ -1037,7 +1037,8 @@ QString QPropertyBindingError::description() const
   Returns the metatype of the property from which the QUntypedBindable was created.
   If the bindable is invalid, an invalid metatype will be returned.
 
-  \sa isValid() //!, QUntypedPropertyBinding::valueMetaType()
+  \sa isValid()
+  //! \sa QUntypedPropertyBinding::valueMetaType()
 */
 
 /*!

src/corelib/text/qbytearrayview.qdoc

@@ -353,6 +353,17 @@
     \sa data(), begin(), end()
 */
 
+/*! //! friend
+    \fn int QByteArrayView::operator==(QByteArrayView lhs, QByteArrayView rhs)
+    \fn int QByteArrayView::operator!=(QByteArrayView lhs, QByteArrayView rhs)
+    \fn int QByteArrayView::operator< (QByteArrayView lhs, QByteArrayView rhs)
+    \fn int QByteArrayView::operator<=(QByteArrayView lhs, QByteArrayView rhs)
+    \fn int QByteArrayView::operator> (QByteArrayView lhs, QByteArrayView rhs)
+    \fn int QByteArrayView::operator>=(QByteArrayView lhs, QByteArrayView rhs)
+
+    Comparison operators for QByteArrayView.
+*/
+
 /*!
     \fn int QByteArrayView::compare(QByteArrayView bv, Qt::CaseSensitivity cs = Qt::CaseSensitive) const
     \since 6.2

src/corelib/text/qchar.cpp

@@ -499,7 +499,7 @@ QT_BEGIN_NAMESPACE
     \enum QChar::Decomposition
 
     This enum type defines the Unicode decomposition attributes. See
-    the \l{Unicode Standard} for a description of the values.
+    the \l{Unicode standard} for a description of the values.
 
     \value NoDecomposition
     \value Canonical
@@ -528,7 +528,7 @@ QT_BEGIN_NAMESPACE
     since 5.3
 
     This enum type defines the Unicode joining type attributes. See the
-    \l{Unicode Standard} for a description of the values.
+    \l{Unicode standard} for a description of the values.
 
     In order to conform to C/C++ naming conventions "Joining_" is prepended
     to the codes used in the Unicode Standard.

src/corelib/time/qcalendar.cpp

@@ -82,7 +82,7 @@ inline size_t qHash(const CalendarName &key, size_t seed = 0) noexcept
 
 namespace QtPrivate {
 
-/*!
+/*
     \internal
     Handles calendar backend registration.
 */
@@ -179,7 +179,7 @@ class QCalendarRegistry
     QStringList backendNames(const QCalendarBackend *backend);
 };
 
-/*!
+/*
     Destroy the registry.
 
     This destroys all registered backends. This destructor should only be called
@@ -194,7 +194,7 @@ QCalendarRegistry::~QCalendarRegistry()
     qDeleteAll(byId);
 }
 
-/*!
+/*
     Registers a custom backend.
 
     A new unique ID is allocated for the \a backend. The registry takes
@@ -218,7 +218,7 @@ void QCalendarRegistry::registerCustomBackend(QCalendarBackend *backend, const Q
     registerBackendLockHeld(backend, names, QCalendar::System::User);
 }
 
-/*!
+/*
     Ensures all system calendars have been instantiated.
 
     This arranges for each system backend to be registered. The method only
@@ -248,7 +248,7 @@ void QCalendarRegistry::ensurePopulated()
 #endif
 }
 
-/*!
+/*
     Helper functions for system backend registration.
 
     This function must be called with write lock held on the registry.
@@ -303,7 +303,7 @@ QCalendarBackend *QCalendarRegistry::registerSystemBackendLockHeld(QCalendar::Sy
     return backend;
 }
 
-/*!
+/*
     Helper function for backend registration.
 
     This function must be called with write lock held on the registry.
@@ -350,7 +350,7 @@ void QCalendarRegistry::registerBackendLockHeld(QCalendarBackend *backend, const
     }
 }
 
-/*!
+/*
     Returns a list of names of the available calendar systems.
 
     Any QCalendarBackend sub-class must be registered before being exposed to Date
@@ -366,7 +366,7 @@ QStringList QCalendarRegistry::availableCalendars()
     return QStringList(byName.keyBegin(), byName.keyEnd());
 }
 
-/*!
+/*
     Returns a pointer to a named calendar backend.
 
     If the given \a name is present in availableCalendars(), the backend
@@ -383,7 +383,7 @@ const QCalendarBackend *QCalendarRegistry::fromName(QAnyStringView name)
     return byName.value(name.toString(), nullptr);
 }
 
-/*!
+/*
     Returns a pointer to a calendar backend, specified by index.
 
     If a calendar with ID \a index is known to the calendar registry, the backend
@@ -409,7 +409,7 @@ const QCalendarBackend *QCalendarRegistry::fromIndex(size_t index)
     return nullptr;
 }
 
-/*!
+/*
     Returns a pointer to a calendar backend, specified by \a system.
 
     This will instantiate the indicated calendar (which will enable fromName()
@@ -442,7 +442,7 @@ const QCalendarBackend *QCalendarRegistry::fromEnum(QCalendar::System system)
     return registerSystemBackendLockHeld(system);
 }
 
-/*!
+/*
     Returns a list of names \a backend was registered with.
 */
 QStringList QCalendarRegistry::backendNames(const QCalendarBackend *backend)
@@ -1138,10 +1138,10 @@ const QCalendarBackend *QCalendarBackend::gregorian()
 */
 
 /*!
-    \fn QCalendar::SystemId::isValid()
+    \fn QCalendar::SystemId::isValid() const
 
-    Returns true if this is a valid calendar implementation identifier, else
-    false.
+    Returns \c true if this is a valid calendar implementation identifier,
+    \c false otherwise.
 
     \sa QCalendar
 */

src/corelib/tools/qhash.cpp

@@ -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 qHashSeed::globalSeed, QHashSeed
+    \sa QHashSeed::globalSeed(), QHashSeed
  */
 void qSetGlobalQHashSeed(int newSeed)
 {

src/corelib/tools/qmap.h

@@ -499,9 +499,11 @@ class QMap
 
 #if QT_DEPRECATED_SINCE(6, 0)
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        //! [qmap-op-it-plus-step]
         friend iterator operator+(iterator it, difference_type j) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        //! [qmap-op-it-minus-step]
         friend iterator operator-(iterator it, difference_type j) { return std::prev(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMap iterators are not random access")
@@ -511,9 +513,11 @@ class QMap
         iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        //! [qmap-op-step-plus-it]
         friend iterator operator+(difference_type j, iterator it) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        //! [qmap-op-step-minus-it]
         friend iterator operator-(difference_type j, iterator it) { return std::prev(it, j); }
 #endif
     };
@@ -566,9 +570,11 @@ class QMap
 
 #if QT_DEPRECATED_SINCE(6, 0)
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        //! [qmap-op-it-plus-step-const]
         friend const_iterator operator+(const_iterator it, difference_type j) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        //! [qmap-op-it-minus-step-const]
         friend const_iterator operator-(const_iterator it, difference_type j) { return std::prev(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMap iterators are not random access")
@@ -578,9 +584,11 @@ class QMap
         const_iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMap iterators are not random access")
+        //! [qmap-op-step-plus-it-const]
         friend const_iterator operator+(difference_type j, const_iterator it) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMap iterators are not random access")
+        //! [qmap-op-step-minus-it-const]
         friend const_iterator operator-(difference_type j, const_iterator it) { return std::prev(it, j); }
 #endif
     };
@@ -1173,9 +1181,11 @@ class QMultiMap
 
 #if QT_DEPRECATED_SINCE(6, 0)
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        //! [qmultimap-op-it-plus-step]
         friend iterator operator+(iterator it, difference_type j) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        //! [qmultimap-op-it-minus-step]
         friend iterator operator-(iterator it, difference_type j) { return std::prev(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMultiMap iterators are not random access")
@@ -1185,9 +1195,11 @@ class QMultiMap
         iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        //! [qmultimap-op-step-plus-it]
         friend iterator operator+(difference_type j, iterator it) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        //! [qmultimap-op-step-minus-it]
         friend iterator operator-(difference_type j, iterator it) { return std::prev(it, j); }
 #endif
     };
@@ -1240,9 +1252,11 @@ class QMultiMap
 
 #if QT_DEPRECATED_SINCE(6, 0)
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        //! [qmultimap-op-it-plus-step-const]
         friend const_iterator operator+(const_iterator it, difference_type j) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        //! [qmultimap-op-it-minus-step-const]
         friend const_iterator operator-(const_iterator it, difference_type j) { return std::prev(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next or std::advance; QMultiMap iterators are not random access")
@@ -1252,9 +1266,11 @@ class QMultiMap
         const_iterator &operator-=(difference_type j) { std::advance(*this, -j); return *this; }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::next; QMultiMap iterators are not random access")
+        //! [qmultimap-op-step-plus-it-const]
         friend const_iterator operator+(difference_type j, const_iterator it) { return std::next(it, j); }
 
         QT_DEPRECATED_VERSION_X_6_0("Use std::prev; QMultiMap iterators are not random access")
+        //! [qmultimap-op-step-minus-it-const]
         friend const_iterator operator-(difference_type j, const_iterator it) { return std::prev(it, j); }
 #endif
     };

src/corelib/tools/qmap.qdoc

@@ -1063,18 +1063,17 @@
     current item.
 */
 
-/*! \fn template <class Key, class T> QMap<Key, T>::iterator operator+(QMap<Key, T>::iterator, difference_type n)
-    \fn template <class Key, class T> QMap<Key, T>::iterator operator+(difference_type n, QMap<Key, T>::iterator)
-    \fn template <class Key, class T> QMap<Key, T>::iterator operator-(QMap<Key, T>::iterator, difference_type n)
-    \fn template <class Key, class T> QMap<Key, T>::iterator operator-(difference_type n, QMap<Key, T>::iterator)
-    \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+=(difference_type n)
-    \fn template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-=(difference_type n)
+/*! //! friends
+    \fn [qmap-op-it-plus-step] template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+(QMap<Key, T>::iterator, difference_type n)
+    \fn [qmap-op-step-plus-it] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+(difference_type n, QMap<Key, T>::iterator)
+    \fn [qmap-op-it-minus-step] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-(QMap<Key, T>::iterator, difference_type n)
+    \fn [qmap-op-step-minus-it] template <class Key, class T> QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-(difference_type n, QMap<Key, T>::iterator)
 
-    \obsolete
+    //! members
+    \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator+=(QMap<Key, T>::iterator::difference_type n)
+    \fn template <class Key, class T> typename QMap<Key, T>::iterator QMap<Key, T>::iterator::operator-=(QMap<Key, T>::iterator::difference_type n)
 
-    \since 6.2
-
-    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+    \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
 
     Moves an iterator by \e{n} positions. These operations can be
     expensive for large values of \e{n}; QMap iterators are not
@@ -1235,18 +1234,17 @@
     current item.
 */
 
-/*! \fn template <class Key, class T> QMap<Key, T>::const_iterator operator+(QMap<Key, T>::const_iterator, difference_type n)
-    \fn template <class Key, class T> QMap<Key, T>::const_iterator operator+(difference_type n, QMap<Key, T>::const_iterator)
-    \fn template <class Key, class T> QMap<Key, T>::const_iterator operator-(QMap<Key, T>::const_iterator, difference_type n)
-    \fn template <class Key, class T> QMap<Key, T>::const_iterator operator-(difference_type n, QMap<Key, T>::const_iterator)
-    \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator+=(difference_type n)
-    \fn template <class Key, class T> QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator-=(difference_type n)
-
-    \obsolete
+/*! //! friends
+    \fn [qmap-op-it-plus-step-const] template <class Key, class T> QMap<Key, T>::const_iterator::operator+(QMap<Key, T>::const_iterator, difference_type n)
+    \fn [qmap-op-step-plus-it-const] template <class Key, class T> QMap<Key, T>::operator+(difference_type n, QMap<Key, T>::const_iterator)
+    \fn [qmap-op-it-minus-step-const] template <class Key, class T> QMap<Key, T>::operator-(QMap<Key, T>::const_iterator, difference_type n)
+    \fn [qmap-op-step-minus-it-const] template <class Key, class T> QMap<Key, T>::operator-(difference_type n, QMap<Key, T>::const_iterator)
 
-    \since 6.2
+    //! members
+    \fn template <class Key, class T> typename QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator+=(QMap<Key, T>::const_iterator::difference_type n)
+    \fn template <class Key, class T> typename QMap<Key, T>::const_iterator QMap<Key, T>::const_iterator::operator-=(QMap<Key, T>::const_iterator::difference_type n)
 
-    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+    \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
 
     Moves an iterator by \e{n} positions. These operations can be
     expensive for large values of \e{n}. QMap iterators are not

src/corelib/tools/qmultimap.qdoc

@@ -1197,16 +1197,18 @@
     current item.
 */
 
-/*! \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator+(QMultiMap<Key, T>::iterator, difference_type n)
-    \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator+(difference_type n, QMultiMap<Key, T>::iterator)
-    \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator-(QMultiMap<Key, T>::iterator, difference_type n)
-    \fn template <class Key, class T> QMultiMap<Key, T>::iterator operator-(difference_type n, QMultiMap<Key, T>::iterator)
-    \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+=(difference_type n)
-    \fn template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-=(difference_type n)
+/*!
+    //! friends
+    \fn [qmultimap-op-it-plus-step] template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+(QMultiMap<Key, T>::iterator, difference_type n)
+    \fn [qmultimap-op-step-plus-it] template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+(difference_type n, QMultiMap<Key, T>::iterator)
+    \fn [qmultimap-op-it-minus-step] template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-(QMultiMap<Key, T>::iterator, difference_type n)
+    \fn [qmultimap-op-step-minus-it] template <class Key, class T> QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-(difference_type n, QMultiMap<Key, T>::iterator)
 
-    \obsolete
+    //! members
+    \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator+=(QMultiMap<Key, T>::iterator::difference_type n)
+    \fn template <class Key, class T> typename QMultiMap<Key, T>::iterator QMultiMap<Key, T>::iterator::operator-=(QMultiMap<Key, T>::iterator::difference_type n)
 
-    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+    \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
 
     Move an iterator by \e{n} positions. These operations can be
     expensive for large values of \e{n}; QMultiMap iterators are not
@@ -1369,16 +1371,18 @@
     current item.
 */
 
-/*! \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator+(QMultiMap<Key, T>::const_iterator, difference_type n)
-    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator+(difference_type n, QMultiMap<Key, T>::const_iterator)
-    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator-(QMultiMap<Key, T>::const_iterator, difference_type n)
-    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator operator-(difference_type n, QMultiMap<Key, T>::const_iterator)
-    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+=(difference_type n)
-    \fn template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-=(difference_type n)
+/*!
+    //! friends
+    \fn [qmultimap-op-it-plus-step-const] template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+(QMultiMap<Key, T>::const_iterator, difference_type n)
+    \fn [qmultimap-op-step-plus-it-const] template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+(difference_type n, QMultiMap<Key, T>::const_iterator)
+    \fn [qmultimap-op-it-minus-step-const] template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-(QMultiMap<Key, T>::const_iterator, difference_type n)
+    \fn [qmultimap-op-step-minus-it-const] template <class Key, class T> QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-(difference_type n, QMultiMap<Key, T>::const_iterator)
 
-    \obsolete
+    //! members
+    \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator+=(QMultiMap<Key, T>::const_iterator::difference_type n)
+    \fn template <class Key, class T> typename QMultiMap<Key, T>::const_iterator QMultiMap<Key, T>::const_iterator::operator-=(QMultiMap<Key, T>::const_iterator::difference_type n)
 
-    Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
+    \deprecated [6.2] Use \c{std::next}, \c{std::prev} or \c{std::advance} instead.
 
     Move an iterator by \e{n} positions. These operations can be
     expensive for large values of \e{n}. QMultiMap iterators are not