Doc: Fix various documentation warnings

These include typos, marking functions as \internal, documenting
trivial things, and fixing the function signatures passed to the
\fn command.

Task-number: QTBUG-71502
Change-Id: I24a9e1f7e1cdb39e5c31b99202bdd593c6b789ff
Reviewed-by: Martin Smith <martin.smith@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Edward Welbourne <edward.welbourne@qt.io>

src/corelib/global/qglobal.cpp

@@ -3796,7 +3796,7 @@ bool qunsetenv(const char *varName)
     dependent delayed translation in the given \a context with the given
     \a comment.
     The \a context is typically a class and also needs to be specified
-    as a string literal. The string literal \a disambiguation should be
+    as a string literal. The string literal \a comment should be
     a short semantic tag to tell apart otherwise identical strings.
 
     The macro tells lupdate to collect the string, and expands to an

src/corelib/global/qglobalstatic.qdoc

@@ -435,6 +435,7 @@
 */
 
 /*!
+    \keyword qglobalstatic-operator-type-ptr
     \fn template <typename T, T *(&innerFunction)(), QBasicAtomicInt &guard> QGlobalStatic<T, innerFunction, guard>::operator Type*()
 
     This function returns the address of the contents of this global static. If
@@ -476,10 +477,11 @@
     by this function. If the contents have already been destroyed, this
     function will return a null pointer.
 
-    This function is equivalent to \l {operator Type *()}. It is provided for
+    This function is equivalent to \l {qglobalstatic-operator-type-ptr}
-    compatibility with the private Q_GLOBAL_STATIC implementation that existed
+    {operator Type *()}. It is provided for compatibility with the private
-    in Qt 4.x and 5.0. New code should avoid using it and should instead treat
+    Q_GLOBAL_STATIC implementation that existed in Qt 4.x and 5.0. New code
-    the object as a smart pointer.
+    should avoid using it and should instead treat the object as a smart
+    pointer.
 */
 
 /*!

src/corelib/io/qdir.cpp

@@ -1040,7 +1040,8 @@ QStringList QDir::nameFilters() const
     list of filters specified by \a nameFilters.
 
     Each name filter is a wildcard (globbing) filter that understands
-    \c{*} and \c{?} wildcards. (See \l{QRegularExpression wildcard matching}.)
+    \c{*} and \c{?} wildcards. See \l{QRegularExpression#Wildcard matching}
+    {QRegularExpression Wildcard Matching}.
 
     For example, the following code sets three name filters on a QDir
     to ensure that only files with extensions typically used for C++
@@ -2120,8 +2121,8 @@ QString QDir::rootPath()
     patterns in the list of \a filters; otherwise returns \c false. The
     matching is case insensitive.
 
-    \sa {QRegularExpression Wildcard matching}, QRegularExpression::wildcardToRegularExpression(),
+    \sa {QRegularExpression#Wildcard matching}{QRegularExpression Wildcard Matching},
-      entryList(), entryInfoList()
+        entryList(), entryInfoList()
 */
 bool QDir::match(const QStringList &filters, const QString &fileName)
 {
@@ -2143,8 +2144,8 @@ bool QDir::match(const QStringList &filters, const QString &fileName)
     contain multiple patterns separated by spaces or semicolons.
     The matching is case insensitive.
 
-    \sa {QRegularExpression wildcard matching}, QRegularExpression::wildcardToRegularExpression,
+    \sa {QRegularExpression#Wildcard matching}{QRegularExpression Wildcard Matching},
-      entryList(), entryInfoList()
+        entryList(), entryInfoList()
 */
 bool QDir::match(const QString &filter, const QString &fileName)
 {

src/corelib/io/qprocess.cpp

@@ -112,12 +112,12 @@ QT_BEGIN_NAMESPACE
     \relates QProcess
 
     Disables the
-    \l {QProcess::start(const QString &, OpenMode)}{QProcess::start()}
+    \l {QProcess::start(const QString &, QIODevice::OpenMode)}
-    overload taking a single string.
+    {QProcess::start}() overload taking a single string.
     In most cases where it is used, the user intends for the first argument
     to be treated atomically as per the other overload.
 
-    \sa QProcess::start(const QString &command, OpenMode mode)
+    \sa QProcess::start(const QString &command, QIODevice::OpenMode mode)
 */
 
 /*!
@@ -2557,7 +2557,7 @@ bool QProcess::startDetached(const QString &program,
     After the \a command string has been split and unquoted, this function
     behaves like the overload which takes the arguments as a string list.
 
-    \sa start(const QString &command, OpenMode mode)
+    \sa start(const QString &command, QIODevice::OpenMode mode)
 */
 bool QProcess::startDetached(const QString &command)
 {

src/corelib/kernel/qdeadlinetimer.cpp

@@ -720,6 +720,11 @@ QDeadlineTimer QDeadlineTimer::addNSecs(QDeadlineTimer dt, qint64 nsecs) Q_DECL_
   Returns the time remaining before the deadline.
  */
 
+/*!
+  \fn QPair<qint64, unsigned> QDeadlineTimer::_q_data() const
+  \internal
+*/
+
 // the rest of the functions are in qelapsedtimer_xxx.cpp
 
 QT_END_NAMESPACE

src/corelib/kernel/qeventdispatcher_cf.mm

@@ -58,7 +58,7 @@
 
 QT_USE_NAMESPACE
 
-/*!
+/*
     During scroll view panning, and possibly other gestures, UIKit will
     request a switch to UITrackingRunLoopMode via GSEventPushRunLoopMode,
     which records the new runloop mode and stops the current runloop.

src/corelib/kernel/qtimer.cpp

@@ -571,43 +571,43 @@ void QTimer::singleShot(int msec, Qt::TimerType timerType, const QObject *receiv
 */
 
 /*!
-    \fn template<typename Functor> QMetaObject::Connection callOnTimeout(Functor functor, Qt::ConnectionType connectionType = Qt::AutoConnection)
+    \fn template <typename Functor> QMetaObject::Connection QTimer::callOnTimeout(Functor slot, Qt::ConnectionType connectionType = Qt::AutoConnection)
     \since 5.12
     \overload
 
-    Creates a connection from the timeout() signal to \a functor, and returns a
+    Creates a connection from the timeout() signal to \a slot, and returns a
     handle to the connection.
 
     This method is provided for convenience.
-    It's equivalent to calling \c {QObject::connect(timer, &QTimer::timeout, timer, functor, connectionType)}.
+    It's equivalent to calling \c {QObject::connect(timer, &QTimer::timeout, timer, slot, connectionType)}.
 
     \sa QObject::connect(), timeout()
 */
 
 /*!
-    \fn template<typename Functor> QMetaObject::Connection callOnTimeout(QObject *context, Functor functor, Qt::ConnectionType connectionType = Qt::AutoConnection)
+    \fn template <typename Functor> QMetaObject::Connection QTimer::callOnTimeout(const QObject *context, Functor slot, Qt::ConnectionType connectionType = Qt::AutoConnection)
     \since 5.12
     \overload callOnTimeout()
 
-    Creates a connection from the timeout() signal to \a functor to be placed in a specific
+    Creates a connection from the timeout() signal to \a slot to be placed in a specific
     event loop of \a context, and returns a handle to the connection.
 
     This method is provided for convenience. It's equivalent to calling
-    \c {QObject::connect(timer, &QTimer::timeout, context, functor, connectionType)}.
+    \c {QObject::connect(timer, &QTimer::timeout, context, slot, connectionType)}.
 
     \sa QObject::connect(), timeout()
 */
 
 /*!
-    \fn template<typename PointerToMemberFunction> QMetaObject::Connection callOnTimeout(QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType connectionType = Qt::AutoConnection)
+    \fn template <typename PointerToMemberFunction> QMetaObject::Connection QTimer::callOnTimeout(const QObject *receiver, PointerToMemberFunction slot, Qt::ConnectionType connectionType = Qt::AutoConnection)
     \since 5.12
     \overload callOnTimeout()
 
-    Creates a connection from the timeout() signal to the \a method in the \a receiver object. Returns
+    Creates a connection from the timeout() signal to the \a slot in the \a receiver object. Returns
     a handle to the connection.
 
     This method is provided for convenience. It's equivalent to calling
-    \c {QObject::connect(timer, &QTimer::timeout, receiver, method, connectionType)}.
+    \c {QObject::connect(timer, &QTimer::timeout, receiver, slot, connectionType)}.
 
     \sa QObject::connect(), timeout()
 */

src/corelib/tools/qbytearray.cpp

@@ -3076,7 +3076,7 @@ bool QByteArray::endsWith(const char *str) const
     return qstrncmp(d->data() + d->size - len, str, len) == 0;
 }
 
-/*!
+/*
     Returns true if \a c is an uppercase Latin1 letter.
     \note The multiplication sign 0xD7 and the sz ligature 0xDF are not
     treated as uppercase Latin1.
@@ -3112,7 +3112,7 @@ bool QByteArray::isUpper() const
     return true;
 }
 
-/*!
+/*
     Returns true if \a c is an lowercase Latin1 letter.
     \note The division sign 0xF7 is not treated as lowercase Latin1,
     but the small y dieresis 0xFF is.

src/corelib/tools/qmap.cpp

@@ -537,7 +537,7 @@ void QMapDataBase::freeData(QMapDataBase *d)
     \sa operator=()
 */
 
-/*! \fn template <class Key, class T> QMap<Key, T>::QMap(const std::map<Key, T> & other)
+/*! \fn template <class Key, class T> QMap<Key, T>::QMap(const typename std::map<Key, T> & other)
 
     Constructs a copy of \a other.
 

src/corelib/tools/qregularexpression.cpp

@@ -2000,8 +2000,8 @@ QString QRegularExpression::wildcardToRegularExpression(const QString &pattern)
 
     \since 5.12
 
-    Returns the expression wrapped between the \c{\A} and \c{\z} anchors to be
+    Returns the \a expression wrapped between the \c{\A} and \c{\z} anchors to
-    used for exact matching.
+    be used for exact matching.
 
     \sa {Porting from QRegExp's Exact Matching}
 */

src/corelib/tools/qshareddata.cpp

@@ -579,6 +579,13 @@ QT_BEGIN_NAMESPACE
     the shared data object if the reference count became 0.
  */
 
+/*! \fn template <class T> T *QExplicitlySharedDataPointer<T>::take()
+    \since 5.12
+
+    Returns a pointer to the shared object, and resets \e this to be null.
+    That is, this function sets the \e{d pointer} of \e this to \c nullptr.
+ */
+
 /*! \fn template <class T> QExplicitlySharedDataPointer<T>::operator bool () const
     Returns \c true if the \e{d pointer} of \e this is \e not null.
  */

src/corelib/tools/qstring.cpp

@@ -254,7 +254,7 @@ inline RetType UnrollTailLoop<0>::exec(Number, RetType returnIfExited, Functor1,
 /*!
  * \internal
  *
- * Searches for character \a \c in the string \a str and returns a pointer to
+ * Searches for character \a c in the string \a str and returns a pointer to
  * it. Unlike strchr() and wcschr() (but like glibc's strchrnul()), if the
  * character is not found, this function returns a pointer to the end of the
  * string -- that is, \c{str.end()}.

src/corelib/tools/qtimezone.cpp

@@ -217,7 +217,7 @@ Q_GLOBAL_STATIC(QTimeZoneSingleton, global_tz);
 
     This class includes data obtained from the CLDR data files under the terms
     of the Unicode Data Files and Software License. See
-    \l{Unicode CLDR (Unicode Common Locale Data Repository)} for the details.
+    \l{Unicode Common Locale Data Repository (CLDR)} for details.
 
     \sa QDateTime
 */