Add documentation for the Intents QML API

Change-Id: Ib1a99c2aed7a09a86635ee1d2300e023b924cfbe
Reviewed-by: Dominik Holland <dominik.holland@pelagicore.com>

3 files changed, 243 insertions, 0 deletions

diff --git a/src/intent-client-lib/intentclient.cpp b/src/intent-client-lib/intentclient.cpp
index 786d30fc..0c5d5264 100644
--- a/src/intent-client-lib/intentclient.cpp
+++ b/src/intent-client-lib/intentclient.cpp
@@ -55,6 +55,34 @@
 
 QT_BEGIN_NAMESPACE_AM
 
+/*!
+    \qmltype IntentClient
+    \inqmlmodule QtApplicationManager
+    \ingroup common-singletons
+    \brief Singleton that provides functions to create Intent requests.
+
+    This type can be used both in applications as well as within the System-UI to create intent
+    requests. This type is only the factory, returning instances of the type IntentRequest. See
+    the IntentRequest documentation for details on how to actually handle these asynchronous calls.
+
+    Here is a fairly standard way to send an intent request and react on its result (or error
+    message):
+
+    \qml
+    MouseArea {
+        onClicked: {
+            var request = IntentClient.sendIntentRequest("show-image", { url: "file://x.png" })
+            request.onReplyReceived.connect(function() {
+                if (request.succeeded)
+                    var result = request.result
+                else
+                    console.log("Intent request failed: " + request.errorMessage)
+            })
+        }
+    }
+    \endqml
+*/
+
 IntentClient *IntentClient::s_instance = nullptr;
 
 IntentClient *IntentClient::createInstance(IntentClientSystemInterface *systemInterface)
@@ -143,11 +171,34 @@ void IntentClient::unregisterHandler(IntentHandler *handler)
     }
 }
 
+/*! \qmlmethod IntentRequest IntentClient::sendIntentRequest(string intentId, var parameters)
+
+    Sends a request for an intent with the given \a intentId to the system. The additional
+    \a parameters are specific to the requested \a intentId, but the format is always the same: a
+    standard JavaScript object, which can also be just empty if the requested intent doesn't
+    require any parameters.
+
+    Returns an IntentRequest object that can be used to track this asynchronous request.
+
+    \note The returned object has JavaScript ownership, which means that you do not have to worry
+          about freeing resources. Even just ignoring the return value is fine, if you are not
+          interested in the result (or error condition) of your request.
+*/
 IntentClientRequest *IntentClient::sendIntentRequest(const QString &intentId, const QVariantMap &parameters)
 {
     return sendIntentRequest(intentId, QString(), parameters);
 }
 
+/*! \qmlmethod IntentRequest IntentClient::sendIntentRequest(string intentId, string applicationId, var parameters)
+    \overload
+
+    Instead of letting the system-ui (or the user) choose which application should handle your
+    request, you can use this overload to hardcode the \a applicationId that is required to handle
+    it. The request will fail, if this specified application doesn't exist or can't handle this
+    specific request, even though other applications would be able to do it.
+
+    \sa sendIntentRequest
+*/
 IntentClientRequest *IntentClient::sendIntentRequest(const QString &intentId, const QString &applicationId,
                                                      const QVariantMap &parameters)
 {
diff --git a/src/intent-client-lib/intentclientrequest.cpp b/src/intent-client-lib/intentclientrequest.cpp
index 903e335b..27358307 100644
--- a/src/intent-client-lib/intentclientrequest.cpp
+++ b/src/intent-client-lib/intentclientrequest.cpp
@@ -51,6 +51,118 @@
 
 QT_BEGIN_NAMESPACE_AM
 
+/*! \qmltype IntentRequest
+    \inqmlmodule QtApplicationManager
+    \ingroup common-non-instantiable
+    \brief Each instance represents an outgoing or incoming intent request.
+
+    This type is used both in applications as well as within the System-UI to represent an intent
+    request. This type can not be instantiated directly, but will be returned by
+    IntentClient::sendIntentRequest() (for outgoing requests to the system) and
+    IntentHandler::requestReceived() (for incoming requests to the application)
+
+    See the IntentClient type for a short example on how to send intent requests to the system.
+
+    The IntentHandler documenatation provides an example showing the use of this type when receiving
+    requests from the system.
+*/
+
+/*! \qmlproperty uuid IntentRequest::requestId
+    \readonly
+
+    Every intent request in the system gets an unique requestId assigned by the server that will be
+    used throughout the life-time of the request in every context (requesting application, handling
+    application and intent server).
+    \note Since this requestId is generated by the server, any IntentRequest object generated by
+          IntentClient::sendIntentRequest() will start with a null requestId. The property will
+          be updated asynchronously once the server has assigned a new requestId to the
+          incoming request.
+
+    \note Constant for requests received by IntentHandlers, valid on both sent and received requests.
+*/
+
+/*! \qmlproperty IntentRequest::Direction IntentRequest::direction
+    \readonly
+
+    This property describes if this instance is an outgoing or incoming intent request:
+
+    \list
+    \li IntentRequest.ToSystem - The request object was generated by IntentClient::sendIntentRequest(),
+                                 i.e. this request is sent out to the system side for handling.
+    \li IntentRequest.ToApplication - The request object was received by IntentHandler::requestReceived(),
+                                      i.e. this request was sent from the system side to the
+                                      application for handling.
+    \endlist
+
+    \note Constant, valid on both sent and received requests.
+*/
+
+/*! \qmlproperty string IntentRequest::intentId
+    \readonly
+
+    The requested intent id.
+
+    \note Constant, valid on both sent and received requests.
+*/
+
+/*! \qmlproperty string IntentRequest::applicationId
+    \readonly
+
+    The id of the application which should be handling this request. Returns an empty string if
+    no specific application was requested.
+
+    \note Constant, valid on both sent and received requests.
+*/
+
+/*! \qmlproperty var IntentRequest::parameters
+    \readonly
+
+    All parameters attached to the request as a JavaScript object.
+
+    \note Constant, valid on both sent and received requests.
+*/
+
+/*! \qmlproperty bool IntentRequest::succeeded
+    \readonly
+
+    As soon as the replyReceived() signal has been emitted, this property will show if the
+    intent request was actually successful.
+
+    \note Valid only on sent requests.
+*/
+
+/*! \qmlproperty string IntentRequest::errorMessage
+    \readonly
+
+    As soon as the replyReceived() signal has been emitted, this property will hold a potential
+    error message in case the request failed.
+
+    \note Valid only on sent requests.
+
+    \sa succeeded
+*/
+
+/*! \qmlproperty var IntentRequest::result
+    \readonly
+
+    As soon as the replyReceived() signal has been emitted, this property will hold the result in
+    form of a JavaScript object in case the request succeeded.
+
+    \note Valid only on sent requests.
+
+    \sa succeeded
+*/
+
+/*! \qmlsignal IntentRequest::replyReceived()
+
+    This signal gets emitted when a reply to an intent request is available. The signal handler
+    needs to check the succeeded property to decided whether errorMessage or result are actually
+    valid.
+
+    \note This signal will only ever by emitted for request objects created by
+          IntentClient.sendIntentRequest().
+*/
+
 
 IntentClientRequest::Direction IntentClientRequest::direction() const
 {
@@ -104,6 +216,18 @@ QString IntentClientRequest::errorMessage() const
     return m_errorMessage;
 }
 
+/*! \qmlmethod IntentRequest::sendReply(var result)
+
+    An IntentHandler needs to call this function to send its \a result back to the system in reply
+    to an request received via IntentHandler::requestReceived().
+
+    Only either sendReply() or sendErrorReply() can be used on a single IntentRequest.
+
+    \note This function only works for request objects received from IntentHandler::requestReceived().
+          It will simply do nothing on requests created by IntentClient::sendIntentRequest().
+
+    \sa sendErrorReply
+*/
 void IntentClientRequest::sendReply(const QVariantMap &result)
 {
     //TODO: check that result only contains basic datatypes. convertFromJSVariant() does most of
@@ -126,6 +250,18 @@ void IntentClientRequest::sendReply(const QVariantMap &result)
     }
 }
 
+/*! \qmlmethod IntentRequest::sendErrorReply(string errorMessage)
+
+    IntentHandlers can use this function to indicate that they are unable to handle a request that
+    they received via IntentHandler::requestReceived(), stating the reason in \a errorMessage.
+
+    Only either sendReply() or sendErrorReply() can be used on a single IntentRequest.
+
+    \note This function only works for request objects received from IntentHandler::requestReceived().
+          It will simply do nothing on requests created by IntentClient::sendIntentRequest().
+
+    \sa sendReply
+*/
 void IntentClientRequest::sendErrorReply(const QString &errorMessage)
 {
     if (m_direction == Direction::ToSystem) {
diff --git a/src/intent-client-lib/intenthandler.cpp b/src/intent-client-lib/intenthandler.cpp
index b32d08a2..24579aef 100644
--- a/src/intent-client-lib/intenthandler.cpp
+++ b/src/intent-client-lib/intenthandler.cpp
@@ -45,6 +45,62 @@
 
 QT_BEGIN_NAMESPACE_AM
 
+/*! \qmltype IntentHandler
+    \inqmlmodule QtApplicationManager.Application
+    \ingroup common-instantiatable
+    \brief A handler for intent requests received by applications.
+
+    Any application that has intents listed in its manifest file needs to have a corresponding
+    IntentHandler instance that is actually able to handle incoming requests. This class gives
+    you the flexibility to handle multiple, different intent ids via a single IntentHandler
+    instance or have a dedicated IntentHandler instance for every intent id (or any combination of
+    those).
+
+    Here is a fairly standard way to handle an incoming intent request and send out a result or
+    error message:
+
+    \qml
+    Image {
+        id: viewer
+    }
+
+    IntentHandler {
+        intentIds: [ "show-image" ]
+        onRequestReceived: {
+            var url = request.parameters["url"]
+            if (!url.startsWith("file://")) {
+                request.sendErrorReply("Only file:// urls are supported")
+            } else {
+                viewer.source = url
+                request.sendReply({ "status": source.status })
+            }
+        }
+    }
+    \endqml
+
+*/
+
+/*! \qmlproperty list<string> IntentHandler::intentIds
+
+    Every handler needs to register at least one unique intent id that it will handle. Having
+    multiple IntentHandlers that are registering the same intent id is not possible.
+
+    \note Any changes to this property after component completion will have no effect. This
+          restriction will likely be removed in a future update.
+*/
+
+/*! \qmlsignal IntentHandler::requestReceived(IntentRequest request)
+
+    This signal will be emitted once for every incoming intent \a request that this handler was
+    registered for via its intentIds property.
+    Handling the request can be done synchronously or asynchronously. As soon as your handler has
+    either produced a result or detected an error condition, it should call either
+    IntentClientRequest::sendReply() or IntentClientRequest::sendErrorReply respectively to send a
+    reply back to the requesting party.
+    Only the first call to one of these functions will have any effect. Any further invocations
+    will be ignored.
+*/
+
 IntentHandler::IntentHandler(QObject *parent)
     : QObject(parent)
 { }