Add OTA QML documentation.

And add documentation for signals in C++ API.

Change-Id: Ibd00c8dcebca3f36b729122031b5f84bcfbdb261
Reviewed-by: Topi Reiniö <topi.reinio@theqtcompany.com>

2 files changed, 325 insertions, 19 deletions

diff --git a/src/imports/pluginmain.cpp b/src/imports/pluginmain.cpp
index ba4c456..0fe8a9b 100644
--- a/src/imports/pluginmain.cpp
+++ b/src/imports/pluginmain.cpp
@@ -32,10 +32,265 @@
 QT_BEGIN_NAMESPACE
 
 /*!
-
     \inqmlmodule QtOTAUpdate
     \qmltype OTAClient
     \instantiates QOTAClient
+    \brief Main interface to the OTA functionality.
+
+    OTAClient provides an API to execute OTA tasks. Offline operations include
+    querying the booted and rollback system version details and atomically
+    performing the rollbacks. Online operations include fetching a new system
+    version from a remote server and atomically performing system updates.
+
+    Using this API is safe and won't leave the system in an inconsistent state,
+    even if the power fails half-way through.
+*/
+
+/*!
+    \qmlproperty string OTAClient::clientVersion
+    \readonly
+
+    This is a convenience property that holds a string containing the booted system's version.
+    \sa clientInfo
+*/
+
+/*!
+    \qmlproperty string OTAClient::clientDescription
+    \readonly
+
+    This is a convenience property that holds a string containing the booted system's description.
+    \sa clientInfo
+*/
+
+/*!
+    \qmlproperty string OTAClient::clientRevision
+    \readonly
+
+    This property holds a string containing the booted system's revision (a checksum in the OSTree
+    repository).
+*/
+
+/*!
+    \qmlproperty string OTAClient::clientInfo
+    \readonly
+
+    This property holds a JSON-formatted string containing the booted system's OTA metadata.
+    Metadata is bundled with each system's version.
+*/
+
+/*!
+    \qmlproperty string OTAClient::serverVersion
+    \readonly
+
+    This is a convenience property that holds a string containing the system's version on a server.
+    \sa serverInfo
+*/
+
+/*!
+    \qmlproperty string OTAClient::serverDescription
+    \readonly
+
+    This is a convenience property that holds a string containing the system's description on a server.
+    \sa serverInfo
+*/
+
+/*!
+    \qmlproperty string OTAClient::serverRevision
+    \readonly
+
+    This property holds a string containing the system's revision on a server (a checksum in the
+    OSTree repository).
+*/
+
+/*!
+    \qmlproperty string OTAClient::serverInfo
+    \readonly
+
+    This property holds a JSON-formatted string containing OTA metadata for the system on a server.
+    Metadata is bundled with each system's version.
+*/
+
+/*!
+    \qmlproperty string OTAClient::rollbackVersion
+    \readonly
+
+    This is a convenience property that holds a string containing the rollback system's version.
+    \sa rollbackInfo
+*/
+
+/*!
+    \qmlproperty string OTAClient::rollbackDescription
+    \readonly
+
+    This is a convenience property that holds a string containing the rollback system's description.
+    \sa rollbackInfo
+*/
+
+/*!
+    \qmlproperty string OTAClient::rollbackRevision
+    \readonly
+
+    This property holds a string containing the rollback system's revision (a checksum in the OSTree
+    repository).
+*/
+
+/*!
+    \qmlproperty string OTAClient::rollbackInfo
+    \readonly
+
+    This property holds a JSON-formatted string containing the rollback system's OTA metadata.
+    Metadata is bundled with each system's version.
+
+    \sa rollback()
+*/
+
+/*!
+    \qmlsignal OTAClient::rollbackInfoChanged()
+
+    This signal is emitted when rollback info changes. Rollback info changes
+    when calling rollback().
+*/
+
+/*!
+    \qmlmethod bool OTAClient::fetchServerInfo()
+
+    Fetch OTA metadata from a server and update the local cache. This
+    metadata contains information on what system version is available on a
+    server. The cache is persistent as it is stored on the disk.
+
+    This method is asynchronous and returns immediately. The return value
+    holds whether the operation was started successfully.
+
+    \sa fetchServerInfoFinished(), updateAvailable, serverInfo
+*/
+
+/*!
+    \qmlsignal OTAClient::fetchServerInfoFinished(bool success)
+
+    This is a notifier signal for fetchServerInfo(). The \a success argument
+    indicates whether the operation was successful.
+*/
+
+/*!
+    \qmlsignal OTAClient::serverInfoChanged()
+
+    Server info can change when calling fetchServerInfo(). If OTA metadata on
+    the server is different from the local cache, the local cache is updated and
+    this signal is emitted.
+*/
+
+/*!
+    \qmlmethod bool OTAClient::update()
+
+    Fetch an OTA update from a server and perform the system update.
+
+    This method is asynchronous and returns immediately. The return value
+    holds whether the operation was started successfully.
+
+    \sa updateFinished(), fetchServerInfo, restartRequired
+*/
+
+/*!
+    \qmlsignal OTAClient::updateFinished(bool success)
+
+    This is a notifier signal for update(). The \a success argument
+    indicates whether the operation was successful.
+*/
+
+/*!
+    \qmlmethod bool OTAClient::rollback()
+
+    Rollback to the previous system version.
+
+    This method is asynchronous and returns immediately. The return value
+    holds whether the operation was started successfully.
+
+    \sa rollbackFinished(), restartRequired
+*/
+
+/*!
+    \qmlsignal OTAClient::rollbackFinished(bool success)
+
+    This is a notifier signal for rollback(). The \a success argument
+    indicates whether the operation was successful.
+*/
+
+/*!
+    \qmlproperty bool OTAClient::otaEnabled
+    \readonly
+
+    This property holds whether a device supports OTA updates.
+*/
+
+/*!
+    \qmlproperty bool  OTAClient::initialized
+    \readonly
+
+    This property holds whether the object has completed the initialization.
+
+    When an object of this class is created, it asynchronously (from a non-GUI thread)
+    pre-populates the internal state and sets this property accordingly, and signals
+    initializationFinished().
+
+    Initialization is fast if there are no other processes locking access to the OSTree
+    repository on a device. This could happen if there is some other process currently
+    writing to the OSTree repository, for example, a daemon calling fetchServerInfo().
+
+    \sa initializationFinished()
+*/
+
+/*!
+    \qmlproperty string OTAClient::error
+    \readonly
+
+    This property holds a string containing the last error occurred.
+*/
+
+/*!
+    \qmlsignal OTAClient::errorOccurred(string error);
+
+    This signal is emitted when an error occurs. The \a error argument holds
+    the error message.
+*/
+
+/*!
+    \qmlproperty bool OTAClient::updateAvailable
+    \readonly
+
+    Holds a bool indicating the availability of a system update. This information
+    is cached - to update the local cache, call fetchServerInfo().
+
+    \sa update()
+*/
+
+/*!
+    \qmlsignal OTAClient::updateAvailableChanged(bool available)
+
+    This signal is emitted when the value of updateAvailable changes. The
+    \a available argument holds whether a system update is available for
+    default system.
+*/
+
+/*!
+    \qmlproperty bool OTAClient::restartRequired
+    \readonly
+
+    Holds a bool indicating whether reboot is required. Reboot is required
+    after update() and rollback() to boot into the new default system.
+*/
+
+/*!
+    \qmlsignal OTAClient::restartRequiredChanged(bool required)
+
+    This signal is emitted when the value of restartRequired changes. The
+    \a required argument holds whether reboot is required.
+*/
+
+/*!
+    \qmlsignal OTAClient::initializationFinished()
+
+    This signal is emitted when the object has finished initialization. Only after
+    this signal has arrived, the object is ready for use.
 */
 
 static QObject *otaClientSingleton(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
diff --git a/src/lib/qotaclient.cpp b/src/lib/qotaclient.cpp
index eb0297f..53e4b9c 100644
--- a/src/lib/qotaclient.cpp
+++ b/src/lib/qotaclient.cpp
@@ -238,7 +238,7 @@ QString QOTAClientPrivate::revision(QueryTarget target) const
     \inmodule qtotaupdate
     \brief Main interface to the OTA functionality.
 
-    This class provides API to perform OTA tasks. Offline operations include
+    This class provides an API to execute OTA tasks. Offline operations include
     querying the booted and rollback system version details and atomically
     performing the rollbacks. Online operations include fetching a new system
     version from a remote server and atomically performing system updates.
@@ -268,6 +268,50 @@ QString QOTAClientPrivate::revision(QueryTarget target) const
     indicates whether the operation was successful.
 */
 
+/*!
+    \fn void QOTAClient::serverInfoChanged()
+
+    Server info can change when calling fetchServerInfo(). If OTA metadata on
+    the server is different from the local cache, the local cache is updated and
+    this signal is emitted.
+*/
+
+/*!
+    \fn void QOTAClient::rollbackInfoChanged()
+
+    This signal is emitted when rollback info changes. Rollback info changes
+    when calling rollback().
+*/
+
+/*!
+    \fn void QOTAClient::updateAvailableChanged(bool available)
+
+    This signal is emitted when the value of updateAvailable changes. The
+    \a available argument holds whether a system update is available for
+    default system.
+*/
+
+/*!
+    \fn void QOTAClient::restartRequiredChanged(bool required)
+
+    This signal is emitted when the value of restartRequired changes. The
+    \a required argument holds whether reboot is required.
+*/
+
+/*!
+    \fn void QOTAClient::errorOccurred(const QString &error)
+
+    This signal is emitted when an error occurs. The \a error argument holds
+    the error message.
+*/
+
+/*!
+    \fn void QOTAClient::initializationFinished()
+
+    This signal is emitted when the object has finished initialization. Only after
+    this signal has arrived, the object is ready for use.
+*/
+
 QOTAClient::QOTAClient(QObject *parent) : QObject(parent),
     d_ptr(new QOTAClientPrivate(this))
 {
@@ -295,9 +339,10 @@ QOTAClient::~QOTAClient()
     metadata contains information on what system version is available on a
     server. The cache is persistent as it is stored on the disk.
 
-    This method is asynchronous and returns immediately, see fetchServerInfoFinished().
+    This method is asynchronous and returns immediately. The return value
+    holds whether the operation was started successfully.
 
-    \sa updateAvailable(), serverInfo()
+    \sa fetchServerInfoFinished(), updateAvailable(), serverInfo()
 */
 bool QOTAClient::fetchServerInfo() const
 {
@@ -312,9 +357,10 @@ bool QOTAClient::fetchServerInfo() const
 /*!
     Fetch an OTA update from a server and perform the system update.
 
-    This method is asynchronous and returns immediately, see updateFinished().
+    This method is asynchronous and returns immediately. The return value
+    holds whether the operation was started successfully.
 
-    \sa fetchServerInfo(), updateAvailable(), restartRequired()
+    \sa updateFinished(), fetchServerInfo(), restartRequired()
 */
 bool QOTAClient::update() const
 {
@@ -329,9 +375,10 @@ bool QOTAClient::update() const
 /*!
     Rollback to the previous system version.
 
-    This method is asynchronous and returns immediately, see rollbackFinished().
+    This method is asynchronous and returns immediately. The return value
+    holds whether the operation was started successfully.
 
-    \sa restartRequired()
+    \sa rollbackFinished(), restartRequired()
 */
 bool QOTAClient::rollback() const
 {
@@ -358,12 +405,12 @@ bool QOTAClient::otaEnabled() const
     \brief whether the object has completed the initialization.
 
     When an object of this class is created, it asynchronously (from a non-GUI thread)
-    pre-populates the internal state and sets the initialized property accordingly, see
+    pre-populates the internal state and sets this property accordingly, and signals
     initializationFinished().
 
     Initialization is fast if there are no other processes locking access to the OSTree
     repository on a device. This could happen if there is some other process currently
-    writing to the OSTree repository, for example a daemon calling fetchServerInfo().
+    writing to the OSTree repository, for example, a daemon calling fetchServerInfo().
 
     \sa initializationFinished()
 */
@@ -388,7 +435,7 @@ QString QOTAClient::errorString() const
     \brief whether a system update is available.
 
     Holds a bool indicating the availability of a system update. This information
-    is cached - to update the local cache call fetchServerInfo().
+    is cached - to update the local cache, call fetchServerInfo().
 */
 bool QOTAClient::updateAvailable() const
 {
@@ -401,9 +448,9 @@ bool QOTAClient::updateAvailable() const
 
 /*!
     \property QOTAClient::restartRequired
-    \brief whether a reboot is required.
+    \brief whether reboot is required.
 
-    Holds a bool indicating whether a reboot is required. A reboot is required
+    Holds a bool indicating whether reboot is required. Reboot is required
     after update() and rollback() to boot into the new default system.
 
 */
@@ -455,8 +502,8 @@ QString QOTAClient::clientRevision() const
     \property QOTAClient::clientInfo
     \brief a QByteArray containing the booted system's OTA metadata.
 
-    Returns JSON formatted QByteArray containing OTA metadata for the booted
-    system. This metadata is bundled with each system's version.
+    Returns JSON-formatted QByteArray containing OTA metadata for the booted
+    system. Metadata is bundled with each system's version.
 */
 QByteArray QOTAClient::clientInfo() const
 {
@@ -502,8 +549,10 @@ QString QOTAClient::serverRevision() const
     \property QOTAClient::serverInfo
     \brief a QByteArray containing the system's OTA metadata on a server.
 
-    Returns JSON formatted QByteArray containing OTA metadata for the system
-    on a server. This metadata is bundled with each system's version.
+    Returns JSON-formatted QByteArray containing OTA metadata for the system
+    on a server. Metadata is bundled with each system's version.
+
+    \sa fetchServerInfo()
 */
 QByteArray QOTAClient::serverInfo() const
 {
@@ -549,8 +598,10 @@ QString QOTAClient::rollbackRevision() const
     \property QOTAClient::rollbackInfo
     \brief a QByteArray containing the rollback system's OTA metadata.
 
-    Returns JSON formatted QByteArray containing OTA metadata for the roolback
-    system. This metadata is bundled with each system's version.
+    Returns JSON-formatted QByteArray containing OTA metadata for the roolback
+    system. Metadata is bundled with each system's version.
+
+    \sa rollback()
 */
 QByteArray QOTAClient::rollbackInfo() const
 {