doc: Change invokeMethod() comments to work with clang

There were four dummy declarations for struct QMetaObject that were
needed by old qdoc to allow documentation of some very complicated
function signatures that old qdoc could not parse. clangqdoc can now
parse these signatures, but, unfortunately, old qdoc is still used to
parse \fn commands in .cpp and .qdoc files, so the dummy declarations
are still needed in struct QMetaObject. However, clangqdoc now
sees that two of the four dummy declarations are actually duplicates
of the other two, and then old qdoc complains when it can't find all
four of the function nodes, when it parses the four \fn commands.
This update removes the duplicate dummy declarations and the two
redundant \fn comments. The remaining two \fn comments are
updated accordingly.

This change also moves a couple of qdoc comments so they are located
with the function definitions that they are documenting.

Change-Id: I85e2492ba0380b01c3700b3dc7db0913d6429701
Reviewed-by: Martin Smith <martin.smith@qt.io>

3 files changed, 14 insertions, 39 deletions

diff --git a/src/corelib/kernel/qmetaobject.cpp b/src/corelib/kernel/qmetaobject.cpp
index aca1799bcb..3560ea1b32 100644
--- a/src/corelib/kernel/qmetaobject.cpp
+++ b/src/corelib/kernel/qmetaobject.cpp
@@ -1589,53 +1589,29 @@ bool QMetaObject::invokeMethodImpl(QObject *object, QtPrivate::QSlotObjectBase *
 */
 
 /*!
-    \fn bool QMetaObject::invokeMethod(QObject *receiver, PointerToMemberFunction function, Qt::ConnectionType type = Qt::AutoConnection, MemberFunctionReturnType *ret = nullptr)
-
-    \since 5.10
-
-    \overload
-*/
-
-/*!
-    \fn bool QMetaObject::invokeMethod(QObject *receiver, PointerToMemberFunction function, MemberFunctionReturnType *ret)
+    \fn bool QMetaObject::invokeMethod(QObject *context, Functor function, Qt::ConnectionType type, FunctorReturnType *ret)
 
     \since 5.10
 
     \overload
 
-    This overload invokes the member function using the connection type Qt::AutoConnection.
+    Invokes the \a function in the event loop of \a context. \a function can be a functor
+    or a pointer to a member function. Returns \c true if the function could be invoked.
+    Returns \c false if there is no such function or the parameters did not match.
+    The return value of the function call is placed in \a ret.
 */
 
 /*!
-    \fn bool QMetaObject::invokeMethod(QObject *context, Functor function, Qt::ConnectionType type = Qt::AutoConnection, FunctorReturnType *ret = nullptr)
+    \fn bool QMetaObject::invokeMethod(QObject *context, Functor function, FunctorReturnType *ret)
 
     \since 5.10
 
     \overload
 
-    Call the functor in the event loop of \a context.
-*/
-
-/*!
-    \fn bool QMetaObject::invokeMethod(QObject *context, Functor function, FunctorReturnType *ret = nullptr)
-
-    \since 5.10
-
-    \overload
-
-    Call the functor in the event loop of \a context using the connection type Qt::AutoConnection.
-*/
-
-/*!
-    \fn QMetaObject::Connection::Connection(const Connection &other)
-
-    Constructs a copy of \a other.
-*/
-
-/*!
-    \fn QMetaObject::Connection::Connection &operator=(const Connection &other)
-
-    Assigns \a other to this connection and returns a reference to this connection.
+    Invokes the \a function in the event loop of \a context using the connection type Qt::AutoConnection.
+    \a function can be a functor or a pointer to a member function. Returns \c true if the function could
+    be invoked. Returns \c false if there is no such member or the parameters did not match.
+    The return value of the function call is placed in \a ret.
 */
 
 /*!
diff --git a/src/corelib/kernel/qobject.cpp b/src/corelib/kernel/qobject.cpp
index 232133c39c..650523d01c 100644
--- a/src/corelib/kernel/qobject.cpp
+++ b/src/corelib/kernel/qobject.cpp
@@ -5032,6 +5032,9 @@ QMetaObject::Connection::Connection(const QMetaObject::Connection &other) : d_pt
         static_cast<QObjectPrivate::Connection *>(d_ptr)->ref();
 }
 
+/*!
+    Assigns \a other to this connection and returns a reference to this connection.
+*/
 QMetaObject::Connection& QMetaObject::Connection::operator=(const QMetaObject::Connection& other)
 {
     if (other.d_ptr != d_ptr) {
diff --git a/src/corelib/kernel/qobjectdefs.h b/src/corelib/kernel/qobjectdefs.h
index b5f7a21565..7d2cc4dcbc 100644
--- a/src/corelib/kernel/qobjectdefs.h
+++ b/src/corelib/kernel/qobjectdefs.h
@@ -466,11 +466,7 @@ struct Q_CORE_EXPORT QMetaObject
                 val1, val2, val3, val4, val5, val6, val7, val8, val9);
     }
 
-#ifdef Q_QDOC
-    template<typename PointerToMemberFunction, typename MemberFunctionReturnType>
-    static bool invokeMethod(QObject *receiver, PointerToMemberFunction function, Qt::ConnectionType type = Qt::AutoConnection, MemberFunctionReturnType *ret = nullptr);
-    template<typename PointerToMemberFunction, typename MemberFunctionReturnType>
-    static bool invokeMethod(QObject *receiver, PointerToMemberFunction function, MemberFunctionReturnType *ret);
+#ifdef Q_CLANG_QDOC
     template<typename Functor, typename FunctorReturnType>
     static bool invokeMethod(QObject *context, Functor function, Qt::ConnectionType type = Qt::AutoConnection, FunctorReturnType *ret = nullptr);
     template<typename Functor, typename FunctorReturnType>