Add basic documentation for QRemoteObjectPendingCall and friends

Change-Id: I359e890b6b4d2ff587f5445c677f04e47e16cdd0
Reviewed-by: Brett Stottlemyer <bstottle@ford.com>

3 files changed, 90 insertions, 0 deletions

diff --git a/src/imports/remoteobjects/plugin.cpp b/src/imports/remoteobjects/plugin.cpp
index 4032a63..2cdf38c 100644
--- a/src/imports/remoteobjects/plugin.cpp
+++ b/src/imports/remoteobjects/plugin.cpp
@@ -55,6 +55,8 @@ struct QtQmlRemoteObjectsResponse {
     QTimer *timer;
 };
 
+
+// documentation updates for this class can be made in remoteobjects-qml.qdoc
 class QtQmlRemoteObjects : public QObject
 {
     Q_OBJECT
diff --git a/src/remoteobjects/doc/src/remoteobjects-qml.qdoc b/src/remoteobjects/doc/src/remoteobjects-qml.qdoc
index cdd3d5c..e69c9be 100644
--- a/src/remoteobjects/doc/src/remoteobjects-qml.qdoc
+++ b/src/remoteobjects/doc/src/remoteobjects-qml.qdoc
@@ -84,3 +84,22 @@ import QtRemoteObjects 5.\1
 
 \section1 QML Types
 */
+
+/*!
+\qmltype QtRemoteObjects
+\inqmlmodule QtRemoteObjects
+\since 5.14
+\brief The QtRemoteObjects global object provides useful functions for working with remote
+       types in QML.
+*/
+
+/*!
+    \qmlmethod Promise QtRemoteObjects::QtRemoteObjects::watch(QRemoteObjectPendingCall reply, int timeout = 30000)
+    Encapsulates the return value from a replica in a JavaScript Promise.
+
+    \qml
+    QtRemoteObjects.watch(replica.fetchDetails(identifier))
+                   .then(function(value) { details = value },
+                         function(error) { console.log("error fetching details:", error) })
+    \endqml
+*/
diff --git a/src/remoteobjects/qremoteobjectpendingcall.cpp b/src/remoteobjects/qremoteobjectpendingcall.cpp
index 5393f12..c7574cf 100644
--- a/src/remoteobjects/qremoteobjectpendingcall.cpp
+++ b/src/remoteobjects/qremoteobjectpendingcall.cpp
@@ -72,6 +72,12 @@ void QRemoteObjectPendingCallWatcherHelper::emitSignals()
     emit finished();
 }
 
+/*!
+    \class QRemoteObjectPendingCall
+    \inmodule QtRemoteObjects
+    \brief Encapsulates the result of an asynchronous method call.
+*/
+
 QRemoteObjectPendingCall::QRemoteObjectPendingCall()
     : d(new QRemoteObjectPendingCallData)
 {
@@ -97,6 +103,12 @@ QRemoteObjectPendingCall &QRemoteObjectPendingCall::operator=(const QRemoteObjec
     return *this;
 }
 
+/*!
+    Returns the return value of the remote call.
+
+    returnValue will only be valid when the remote call has finished and there
+    are no \l {error}s.
+*/
 QVariant QRemoteObjectPendingCall::returnValue() const
 {
     if (!d)
@@ -106,6 +118,20 @@ QVariant QRemoteObjectPendingCall::returnValue() const
     return d->returnValue;
 }
 
+/*!
+    \enum QRemoteObjectPendingCall::Error
+
+    This enum type specifies the possible error values for a remote call:
+
+    \value NoError
+           No error occurred.
+    \value InvalidMessage
+           The default error state prior to the remote call finishing.
+*/
+
+/*!
+    Returns the error, if any, from the remote call.
+*/
 QRemoteObjectPendingCall::Error QRemoteObjectPendingCall::error() const
 {
     if (!d)
@@ -115,6 +141,11 @@ QRemoteObjectPendingCall::Error QRemoteObjectPendingCall::error() const
     return d->error;
 }
 
+/*!
+    Returns true if the remote call has finished, false otherwise.
+
+    A finished call will include a returnValue or \l error.
+*/
 bool QRemoteObjectPendingCall::isFinished() const
 {
     if (!d)
@@ -124,6 +155,9 @@ bool QRemoteObjectPendingCall::isFinished() const
     return d->error != InvalidMessage;
 }
 
+/*!
+    Blocks for up to \a timeout milliseconds, until the remote call has finished.
+*/
 bool QRemoteObjectPendingCall::waitForFinished(int timeout)
 {
     if (!d)
@@ -153,6 +187,15 @@ public:
     Q_DECLARE_PUBLIC(QRemoteObjectPendingCallWatcher)
 };
 
+/*!
+    \class QRemoteObjectPendingCallWatcher
+    \inmodule QtRemoteObjects
+    \brief Provides a QObject-based API for watching a QRemoteObjectPendingCall.
+
+    QRemoteObjectPendingCallWatcher provides a signal indicating when a QRemoteObjectPendingCall
+    has finished, allowing for convenient, non-blocking handling of the call.
+*/
+
 QRemoteObjectPendingCallWatcher::QRemoteObjectPendingCallWatcher(const QRemoteObjectPendingCall &call, QObject *parent)
     : QObject(*new QRemoteObjectPendingCallWatcherPrivate, parent)
     , QRemoteObjectPendingCall(call)
@@ -174,6 +217,11 @@ QRemoteObjectPendingCallWatcher::~QRemoteObjectPendingCallWatcher()
 {
 }
 
+/*!
+    Returns true if the remote call has finished, false otherwise.
+
+    A finished call will include a returnValue or error.
+*/
 bool QRemoteObjectPendingCallWatcher::isFinished() const
 {
     if (!d)
@@ -183,6 +231,9 @@ bool QRemoteObjectPendingCallWatcher::isFinished() const
     return d->error != QRemoteObjectPendingCall::InvalidMessage;
 }
 
+/*!
+    Blocks until the remote call has finished.
+*/
 void QRemoteObjectPendingCallWatcher::waitForFinished()
 {
     if (d) {
@@ -194,6 +245,24 @@ void QRemoteObjectPendingCallWatcher::waitForFinished()
     }
 }
 
+/*!
+    \fn QRemoteObjectPendingCallWatcher::finished(QRemoteObjectPendingCallWatcher *self)
+
+    This signal is emitted when the remote call has finished. A finished call will include a
+    returnValue or error.
+*/
+
+/*!
+    \class QRemoteObjectPendingReply
+    \inmodule QtRemoteObjects
+    \brief A templated version of QRemoteObjectPendingCall.
+*/
+
+/*! \fn template <typename T> T QRemoteObjectPendingReply<T>::returnValue() const
+
+    Returns a strongly typed version of the return value of the remote call.
+*/
+
 QT_END_NAMESPACE
 
 #include "moc_qremoteobjectpendingcall.cpp"