doc: Fix all clang parse errors in QtBase during PCH build

This update eliminates ALL parsing errors when clang parses the
Qt headers to build the precompiled header qdoc needs. These errors
are often cases where an old use of Q_QDOC no longer works because
clang sees the enclosed fake declarations as erroneous.

In a few cases, clang reported errors because two dummy function
declartations under the Q_CLANG_QDOC guard were indistinguishable,
so one of them was removed, and the documentation was patched
accordingly.

Using the macro Q_DECLARE_INTERFACE(...) causes clang to report errors
because the class parametewr is abstract. These uses of the macro are
not needed, so they are removed with #ifndef Q_CLANG_QDOC.

Some declarations of default GL types that had been provided for qdoc
were no longer needed, so they are removed.

Now there are some member function signatures in QDBusPendingReply
and QDBusPendingCall that have very long template clauses and qualifiers
in their signatures. These unwieldy signatures will be unnecessary in the
documentation and will look bad there, but for now they are correct. The
ultimate solution will be to add a metacommand to qdoc, something like
\simplify-signature to tell qdoc to generate the documentation for these
member functions without the long template caluses and qualifiers.

Change-Id: I012cf17a544fbba2ebc71002f31bdc865119bb8e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Topi Reiniö <topi.reinio@qt.io>
Reviewed-by: Martin Smith <martin.smith@qt.io>

10 files changed, 38 insertions, 60 deletions

diff --git a/src/dbus/qdbusargument.cpp b/src/dbus/qdbusargument.cpp
index a33c4f8363..2d1373006d 100644
--- a/src/dbus/qdbusargument.cpp
+++ b/src/dbus/qdbusargument.cpp
@@ -267,7 +267,7 @@ bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)
 */
 
 /*!
-    \fn qdbus_cast(const QDBusArgument &arg)
+    \fn template<typename T> T qdbus_cast(const QDBusArgument &arg, T*)
     \relates QDBusArgument
     \since 4.2
 
diff --git a/src/dbus/qdbusargument.h b/src/dbus/qdbusargument.h
index a6d4e9cd25..ac650d5f62 100644
--- a/src/dbus/qdbusargument.h
+++ b/src/dbus/qdbusargument.h
@@ -158,22 +158,14 @@ QT_END_NAMESPACE
 Q_DECLARE_METATYPE(QDBusArgument)
 QT_BEGIN_NAMESPACE
 
-template<typename T> inline T qdbus_cast(const QDBusArgument &arg
-#ifndef Q_QDOC
-, T * = nullptr
-#endif
-    )
+template<typename T> inline T qdbus_cast(const QDBusArgument &arg, T * = nullptr)
 {
     T item;
     arg >> item;
     return item;
 }
 
-template<typename T> inline T qdbus_cast(const QVariant &v
-#ifndef Q_QDOC
-, T * = nullptr
-#endif
-    )
+template<typename T> inline T qdbus_cast(const QVariant &v, T * = nullptr)
 {
     int id = v.userType();
     if (id == qMetaTypeId<QDBusArgument>())
diff --git a/src/dbus/qdbusconnection.h b/src/dbus/qdbusconnection.h
index ca7adfaaeb..3711981f78 100644
--- a/src/dbus/qdbusconnection.h
+++ b/src/dbus/qdbusconnection.h
@@ -122,9 +122,7 @@ public:
         SubPath = 0x1
         // Reserved = 0xff000000
     };
-#ifndef Q_QDOC
     Q_DECLARE_FLAGS(VirtualObjectRegisterOptions, VirtualObjectRegisterOption)
-#endif
 
     enum ConnectionCapability {
         UnixFileDescriptorPassing = 0x0001
diff --git a/src/dbus/qdbuspendingcall.cpp b/src/dbus/qdbuspendingcall.cpp
index 2a31dd950a..4d0131afff 100644
--- a/src/dbus/qdbuspendingcall.cpp
+++ b/src/dbus/qdbuspendingcall.cpp
@@ -311,7 +311,7 @@ QDBusPendingCall &QDBusPendingCall::operator=(const QDBusPendingCall &other)
     \sa QDBusPendingReply::isFinished()
 */
 /*!
-    \fn bool QDBusPendingReply::isFinished() const
+    \fn template <typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> bool QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::isFinished() const
 
     Returns \c true if the pending call has finished processing and the
     reply has been received. If this function returns \c true, the
@@ -340,7 +340,7 @@ void QDBusPendingCall::waitForFinished()
 }
 
 /*!
-    \fn bool QDBusPendingReply::isValid() const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> bool QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::isValid() const
 
     Returns \c true if the reply contains a normal reply message, false
     if it contains anything else.
@@ -357,7 +357,7 @@ bool QDBusPendingCall::isValid() const
 }
 
 /*!
-    \fn bool QDBusPendingReply::isError() const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> bool QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::isError() const
 
     Returns \c true if the reply contains an error message, false if it
     contains a normal method reply.
@@ -374,7 +374,7 @@ bool QDBusPendingCall::isError() const
 }
 
 /*!
-    \fn QDBusError QDBusPendingReply::error() const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusError QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::error() const
 
     Retrieves the error content of the reply message, if it has
     finished processing. If the reply message has not finished
@@ -395,7 +395,7 @@ QDBusError QDBusPendingCall::error() const
 }
 
 /*!
-    \fn QDBusMessage QDBusPendingReply::reply() const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusMessage QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::reply() const
 
     Retrieves the reply message received for the asynchronous call
     that was sent, if it has finished processing. If the pending call
@@ -445,7 +445,7 @@ bool QDBusPendingCall::setReplyCallback(QObject *target, const char *member)
     \since 4.6
     Creates a QDBusPendingCall object based on the error condition
     \a error. The resulting pending call object will be in the
-    "finished" state and QDBusPendingReply::isError() will return true.
+    "finished" state and QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::isError() will return true.
 
     \sa fromCompletedCall()
 */
diff --git a/src/dbus/qdbuspendingcall.h b/src/dbus/qdbuspendingcall.h
index ec8ba6c541..24b1d6a7ca 100644
--- a/src/dbus/qdbuspendingcall.h
+++ b/src/dbus/qdbuspendingcall.h
@@ -67,7 +67,7 @@ public:
 
     void swap(QDBusPendingCall &other) Q_DECL_NOTHROW { qSwap(d, other.d); }
 
-#ifndef Q_QDOC
+#ifndef Q_CLANG_QDOC
     // pretend that they aren't here
     bool isFinished() const;
     void waitForFinished();
diff --git a/src/dbus/qdbuspendingreply.cpp b/src/dbus/qdbuspendingreply.cpp
index fef6f36432..6aec571563 100644
--- a/src/dbus/qdbuspendingreply.cpp
+++ b/src/dbus/qdbuspendingreply.cpp
@@ -94,7 +94,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply::QDBusPendingReply()
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::QDBusPendingReply()
 
     Creates an empty QDBusPendingReply object. Without assigning a
     QDBusPendingCall object to this reply, QDBusPendingReply cannot do
@@ -102,7 +102,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply::QDBusPendingReply(const QDBusPendingReply &other)
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::QDBusPendingReply(const QDBusPendingReply &other)
 
     Creates a copy of the \a other QDBusPendingReply object. Just like
     QDBusPendingCall and QDBusPendingCallWatcher, this QDBusPendingReply
@@ -111,7 +111,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply::QDBusPendingReply(const QDBusPendingCall &call)
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::QDBusPendingReply(const QDBusPendingCall &call)
 
     Creates a QDBusPendingReply object that will take its contents from
     the \a call pending asynchronous call. This QDBusPendingReply object
@@ -119,7 +119,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply::QDBusPendingReply(const QDBusMessage &message)
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::QDBusPendingReply(const QDBusMessage &message)
 
     Creates a QDBusPendingReply object that will take its contents from
     the message \a message. In this case, this object will be already
@@ -129,7 +129,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply &QDBusPendingReply::operator=(const QDBusPendingReply &other)
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply &QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::operator=(const QDBusPendingReply &other)
 
     Makes a copy of \a other and drops the reference to the current
     pending call. If the current reference is to an unfinished pending
@@ -139,7 +139,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply &QDBusPendingReply::operator=(const QDBusPendingCall &call)
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply &QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::operator=(const QDBusPendingCall &call)
 
     Makes this object take its contents from the \a call pending call
     and drops the reference to the current pending call. If the
@@ -149,7 +149,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply &QDBusPendingReply::operator=(const QDBusMessage &message)
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply &QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::operator=(const QDBusMessage &message)
 
     Makes this object take its contents from the \a message message
     and drops the reference to the current pending call. If the
@@ -171,7 +171,7 @@
  */
 
 /*!
-    \fn int QDBusPendingReply::count() const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> int QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::count() const
 
     Return the number of arguments the reply is supposed to have. This
     number matches the number of non-void template parameters in this
@@ -183,7 +183,7 @@
 */
 
 /*!
-    \fn QVariant QDBusPendingReply::argumentAt(int index) const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QVariant QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::argumentAt(int index) const
 
     Returns the argument at position \a index in the reply's
     contents. If the reply doesn't have that many elements, this
@@ -198,12 +198,7 @@
 */
 
 /*!
-  \typedef QDBusPendingReply::T1
-  \internal
- */
-
-/*!
-    \fn T1 QDBusPendingReply::value() const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> T1 QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::value() const
 
     Returns the first argument in this reply, cast to type \c T1 (the
     first template parameter of this class). This is equivalent to
@@ -221,7 +216,7 @@
 */
 
 /*!
-    \fn QDBusPendingReply::operator T1() const
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::operator T1() const
 
     Returns the first argument in this reply, cast to type \c T1 (the
     first template parameter of this class). This is equivalent to
@@ -239,7 +234,7 @@
 */
 
 /*!
-    \fn void QDBusPendingReply::waitForFinished()
+    \fn template<typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8> void QDBusPendingReply<T1, T2, T3, T4, T5, T6, T7, T8>::waitForFinished()
 
     Suspends the execution of the calling thread until the reply is
     received and processed. After this function returns, isFinished()
diff --git a/src/dbus/qdbuspendingreply.h b/src/dbus/qdbuspendingreply.h
index 4d2c3a7c5a..bc5cd92c84 100644
--- a/src/dbus/qdbuspendingreply.h
+++ b/src/dbus/qdbuspendingreply.h
@@ -108,10 +108,8 @@ namespace QDBusPendingReplyTypes {
     template <>           struct NotVoid<void> { typedef TypeIsVoid Type; };
 } // namespace QDBusPendingReplyTypes
 
-#ifndef Q_CLANG_QDOC
 template<typename T1 = void, typename T2 = void, typename T3 = void, typename T4 = void,
          typename T5 = void, typename T6 = void, typename T7 = void, typename T8 = void>
-#endif
 class QDBusPendingReply:
 #ifdef Q_CLANG_QDOC
     public QDBusPendingCall
@@ -171,7 +169,6 @@ public:
     QDBusError error() const;
     QDBusMessage reply() const;
 
-    typedef QVariant T1;
     inline T1 value() const;
     inline operator T1() const;
 #else
diff --git a/src/dbus/qdbusreply.cpp b/src/dbus/qdbusreply.cpp
index ab361f1674..6abfaf174c 100644
--- a/src/dbus/qdbusreply.cpp
+++ b/src/dbus/qdbusreply.cpp
@@ -81,7 +81,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn template<typename T> QDBusReply<T>::QDBusReply(const QDBusPendingReply &reply)
+    \fn template<typename T> QDBusReply<T>::QDBusReply(const QDBusPendingReply<T> &reply)
     Constructs a QDBusReply object from the pending reply message, \a reply.
 */
 
diff --git a/src/dbus/qdbusreply.h b/src/dbus/qdbusreply.h
index 177b6c6e89..869687ac85 100644
--- a/src/dbus/qdbusreply.h
+++ b/src/dbus/qdbusreply.h
@@ -82,14 +82,10 @@ public:
         other.waitForFinished();
         return *this = other.reply();
     }
-#if defined(Q_CLANG_QDOC)
-    inline QDBusReply(const QDBusPendingReply &reply) { }
-#else
     inline QDBusReply(const QDBusPendingReply<T> &reply)
     {
         *this = static_cast<QDBusPendingCall>(reply);
     }
-#endif
 
     inline QDBusReply(const QDBusError &dbusError = QDBusError())
         : m_error(dbusError), m_data(Type())
diff --git a/src/dbus/qdbusutil.cpp b/src/dbus/qdbusutil.cpp
index 28341a71a8..dc94897ac4 100644
--- a/src/dbus/qdbusutil.cpp
+++ b/src/dbus/qdbusutil.cpp
@@ -331,8 +331,8 @@ namespace QDBusUtil
 
     /*!
         \internal
-        \fn bool QDBusUtil::isValidPartOfObjectPath(const QStringRef &part)
-        See QDBusUtil::isValidObjectPath
+        \fn bool isValidPartOfObjectPath(const QStringRef &part)
+        See isValidObjectPath
     */
     bool isValidPartOfObjectPath(const QStringRef &part)
     {
@@ -349,13 +349,13 @@ namespace QDBusUtil
 
     /*!
         \internal
-        \fn bool QDBusUtil::isValidPartOfObjectPath(const QString &part)
+        \fn bool isValidPartOfObjectPath(const QString &part)
 
         \overload
     */
 
     /*!
-        \fn bool QDBusUtil::isValidInterfaceName(const QString &ifaceName)
+        \fn bool isValidInterfaceName(const QString &ifaceName)
         Returns \c true if this is \a ifaceName is a valid interface name.
 
         Valid interface names must:
@@ -384,7 +384,7 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidUniqueConnectionName(const QStringRef &connName)
+        \fn bool isValidUniqueConnectionName(const QStringRef &connName)
         Returns \c true if \a connName is a valid unique connection name.
 
         Unique connection names start with a colon (":") and are followed by a list of dot-separated
@@ -414,13 +414,13 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidUniqueConnectionName(const QString &connName)
+        \fn bool isValidUniqueConnectionName(const QString &connName)
 
         \overload
     */
 
     /*!
-        \fn bool QDBusUtil::isValidBusName(const QString &busName)
+        \fn bool isValidBusName(const QString &busName)
         Returns \c true if \a busName is a valid bus name.
 
         A valid bus name is either a valid unique connection name or follows the rules:
@@ -462,7 +462,7 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidMemberName(const QStringRef &memberName)
+        \fn bool isValidMemberName(const QStringRef &memberName)
         Returns \c true if \a memberName is a valid member name. A valid member name does not exceed
         255 characters in length, is not empty, is composed only of ASCII letters, digits and
         underscores, but does not start with a digit.
@@ -482,13 +482,13 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidMemberName(const QString &memberName)
+        \fn bool isValidMemberName(const QString &memberName)
 
         \overload
     */
 
     /*!
-        \fn bool QDBusUtil::isValidErrorName(const QString &errorName)
+        \fn bool isValidErrorName(const QString &errorName)
         Returns \c true if \a errorName is a valid error name. Valid error names are valid interface
         names and vice-versa, so this function is actually an alias for isValidInterfaceName.
     */
@@ -498,7 +498,7 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidObjectPath(const QString &path)
+        \fn bool isValidObjectPath(const QString &path)
         Returns \c true if \a path is valid object path.
 
         Valid object paths follow the rules:
@@ -529,7 +529,7 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidBasicType(int type)
+        \fn bool isValidBasicType(int type)
         Returns \c true if \a c is a valid, basic D-Bus type.
      */
     bool isValidBasicType(int c)
@@ -538,7 +538,7 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidFixedType(int type)
+        \fn bool isValidFixedType(int type)
         Returns \c true if \a c is a valid, fixed D-Bus type.
      */
     bool isValidFixedType(int c)
@@ -548,7 +548,7 @@ namespace QDBusUtil
 
 
     /*!
-        \fn bool QDBusUtil::isValidSignature(const QString &signature)
+        \fn bool isValidSignature(const QString &signature)
         Returns \c true if \a signature is a valid D-Bus type signature for one or more types.
         This function returns \c true if it can all of \a signature into valid, individual types and no
         characters remain in \a signature.
@@ -569,7 +569,7 @@ namespace QDBusUtil
     }
 
     /*!
-        \fn bool QDBusUtil::isValidSingleSignature(const QString &signature)
+        \fn bool isValidSingleSignature(const QString &signature)
         Returns \c true if \a signature is a valid D-Bus type signature for exactly one full type. This
         function tries to convert the type signature into a D-Bus type and, if it succeeds and no
         characters remain in the signature, it returns \c true.