doc: Fix remaining qdoc warnings in QtDBus

Added many template clauses to \fn commands. Also added or
modified some uses of Q_CLANG_QDOC in some dbus include files
to work around some seriousl ugly template clauses that could
not be added to \fn commands. Also modified a few parameter
names in the documentation.

The first attempt at making this change caused syncqt to fail
to create QtDBus/QDBusPendingReply. This second attempt works.

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

6 files changed, 36 insertions, 39 deletions

diff --git a/src/dbus/qdbusargument.cpp b/src/dbus/qdbusargument.cpp
index d7f9dcc718..a33c4f8363 100644
--- a/src/dbus/qdbusargument.cpp
+++ b/src/dbus/qdbusargument.cpp
@@ -267,11 +267,11 @@ bool QDBusArgumentPrivate::checkReadAndDetach(QDBusArgumentPrivate *&d)
 */
 
 /*!
-    \fn qdbus_cast(const QDBusArgument &argument)
+    \fn qdbus_cast(const QDBusArgument &arg)
     \relates QDBusArgument
     \since 4.2
 
-    Attempts to demarshall the contents of \a argument into the type
+    Attempts to demarshall the contents of \a arg into the type
     \c{T}. For example:
 
     \snippet code/src_qdbus_qdbusargument.cpp 2
diff --git a/src/dbus/qdbusconnectioninterface.cpp b/src/dbus/qdbusconnectioninterface.cpp
index 2b86eded7f..ebb3803489 100644
--- a/src/dbus/qdbusconnectioninterface.cpp
+++ b/src/dbus/qdbusconnectioninterface.cpp
@@ -378,21 +378,21 @@ void QDBusConnectionInterface::disconnectNotify(const QMetaMethod &signal)
 
 // signals
 /*!
-    \fn QDBusConnectionInterface::serviceRegistered(const QString &serviceName)
+    \fn QDBusConnectionInterface::serviceRegistered(const QString &service)
 
     This signal is emitted by the D-Bus server when the bus service
     name (unique connection name or well-known service name) given by
-    \a serviceName is acquired by this application.
+    \a service is acquired by this application.
 
     Acquisition happens after this application has requested a name using
     registerService().
 */
 
 /*!
-    \fn QDBusConnectionInterface::serviceUnregistered(const QString &serviceName)
+    \fn QDBusConnectionInterface::serviceUnregistered(const QString &service)
 
     This signal is emitted by the D-Bus server when this application
-    loses ownership of the bus service name given by \a serviceName.
+    loses ownership of the bus service name given by \a service.
 */
 
 /*!
diff --git a/src/dbus/qdbuspendingreply.cpp b/src/dbus/qdbuspendingreply.cpp
index ac121038ab..c0baa4a005 100644
--- a/src/dbus/qdbuspendingreply.cpp
+++ b/src/dbus/qdbuspendingreply.cpp
@@ -198,21 +198,9 @@
 */
 
 /*!
-    \fn Type QDBusPendingReply::argumentAt() const
-
-    Returns the argument at position \c Index (which is a template
-    parameter) cast to type \c Type. This function uses template code
-    to determine the proper \c Type type, according to the type list
-    used in the construction of this object.
-
-    Note that, if the reply hasn't arrived, this function causes the
-    calling thread to block until the reply is processed.
-
-    If the reply does not contain an argument at position \c Index or if the
-    reply was an error, this function returns a \c Type object that is default
-    constructed, which may be indistinguishable from a valid value. To reliably
-    determine whether the message was an error, use isError().
-*/
+  \typedef QDBusPendingReply::T1
+  \internal
+ */
 
 /*!
     \fn T1 QDBusPendingReply::value() const
diff --git a/src/dbus/qdbuspendingreply.h b/src/dbus/qdbuspendingreply.h
index 4bf574e140..4d2c3a7c5a 100644
--- a/src/dbus/qdbuspendingreply.h
+++ b/src/dbus/qdbuspendingreply.h
@@ -108,8 +108,10 @@ 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
@@ -150,6 +152,7 @@ public:
     using QDBusPendingReplyData::argumentAt;
 #endif
 
+#ifndef Q_CLANG_QDOC
     template<int Index> inline
     const typename Select<Index>::Type argumentAt() const
     {
@@ -157,6 +160,7 @@ public:
         typedef typename Select<Index>::Type ResultType;
         return qdbus_cast<ResultType>(argumentAt(Index), 0);
     }
+#endif
 
 #if defined(Q_CLANG_QDOC)
     bool isFinished() const;
@@ -167,6 +171,7 @@ 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 aefbb4f9a2..ab361f1674 100644
--- a/src/dbus/qdbusreply.cpp
+++ b/src/dbus/qdbusreply.cpp
@@ -64,7 +64,7 @@ QT_BEGIN_NAMESPACE
     If the remote method call cannot fail, you can skip the error checking:
     \snippet code/src_qdbus_qdbusreply.cpp 1
 
-    However, if it does fail under those conditions, the value returned by QDBusReply::value() is
+    However, if it does fail under those conditions, the value returned by QDBusReply<T>::value() is
     a default-constructed value. It may be indistinguishable from a valid return value.
 
     QDBusReply objects are used for remote calls that have no output
@@ -75,18 +75,18 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QDBusReply::QDBusReply(const QDBusMessage &reply)
+    \fn template<typename T> QDBusReply<T>::QDBusReply(const QDBusMessage &reply)
     Automatically construct a QDBusReply object from the reply message \a reply, extracting the
     first return value from it if it is a success reply.
 */
 
 /*!
-    \fn QDBusReply::QDBusReply(const QDBusPendingReply<T> &reply)
+    \fn template<typename T> QDBusReply<T>::QDBusReply(const QDBusPendingReply &reply)
     Constructs a QDBusReply object from the pending reply message, \a reply.
 */
 
 /*!
-    \fn QDBusReply::QDBusReply(const QDBusPendingCall &pcall)
+    \fn template <typename T> QDBusReply<T>::QDBusReply(const QDBusPendingCall &pcall)
     Automatically construct a QDBusReply object from the asynchronous
     pending call \a pcall. If the call isn't finished yet, QDBusReply
     will call QDBusPendingCall::waitForFinished(), which is a blocking
@@ -97,29 +97,29 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QDBusReply::QDBusReply(const QDBusError &error)
+    \fn template <typename T> QDBusReply<T>::QDBusReply(const QDBusError &error)
     Constructs an error reply from the D-Bus error code given by \a error.
 */
 
 /*!
-    \fn QDBusReply::operator=(const QDBusReply &other)
+    \fn template <typename T> QDBusReply<T>::operator=(const QDBusReply &other)
     Makes this object be a copy of the object \a other.
 */
 
 /*!
-    \fn QDBusReply::operator=(const QDBusError &error)
-    Sets this object to contain the error code given by \a error. You
+    \fn template <typename T> QDBusReply<T>::operator=(const QDBusError &dbusError)
+    Sets this object to contain the error code given by \a dbusError. You
     can later access it with error().
 */
 
 /*!
-    \fn QDBusReply::operator=(const QDBusMessage &message)
+    \fn template <typename T> QDBusReply<T>::operator=(const QDBusMessage &reply)
 
-    Makes this object contain the reply specified by message \a
-    message. If \a message is an error message, this function will
+    Makes this object contain the \a reply message. If \a reply
+    is an error message, this function will
     copy the error code and message into this object
 
-    If \a message is a standard reply message and contains at least
+    If \a reply is a standard reply message and contains at least
     one parameter, it will be copied into this object, as long as it
     is of the correct type. If it's not of the same type as this
     QDBusError object, this function will instead set an error code
@@ -127,7 +127,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QDBusReply::operator=(const QDBusPendingCall &pcall)
+    \fn template <typename T> QDBusReply<T>::operator=(const QDBusPendingCall &pcall)
 
     Makes this object contain the reply specified by the pending
     asynchronous call \a pcall. If the call is not finished yet, this
@@ -145,7 +145,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn bool QDBusReply::isValid() const
+    \fn template <typename T> bool QDBusReply<T>::isValid() const
 
     Returns \c true if no error occurred; otherwise, returns \c false.
 
@@ -153,7 +153,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn const QDBusError& QDBusReply::error() const
+    \fn template<typename T> const QDBusError& QDBusReply<T>::error() const
 
     Returns the error code that was returned from the remote function call. If the remote call did
     not return an error (i.e., if it succeeded), then the QDBusError object that is returned will
@@ -163,12 +163,12 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn const QDBusError& QDBusReply::error()
+    \fn template <typename T> const QDBusError& QDBusReply<T>::error()
     \overload
 */
 
 /*!
-    \fn QDBusReply::value() const
+    \fn template <typename T> QDBusReply<T>::value() const
     Returns the remote function's calls return value. If the remote call returned with an error,
     the return value of this function is undefined and may be undistinguishable from a valid return
     value.
@@ -177,7 +177,7 @@ QT_BEGIN_NAMESPACE
 */
 
 /*!
-    \fn QDBusReply::operator Type() const
+    \fn template <typename T> QDBusReply<T>::operator Type() const
     Returns the same as value().
 
     This function is not available if the remote call returns \c void.
diff --git a/src/dbus/qdbusreply.h b/src/dbus/qdbusreply.h
index 869687ac85..177b6c6e89 100644
--- a/src/dbus/qdbusreply.h
+++ b/src/dbus/qdbusreply.h
@@ -82,10 +82,14 @@ 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())