Document OTA API.

And remove the "What is OSTree" section to reduce
duplicated content. In the OTA blog post, ostree role
is explained better and I will elabore more on that
in Part 2 of the series.

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

3 files changed, 184 insertions, 2 deletions

diff --git a/src/imports/pluginmain.cpp b/src/imports/pluginmain.cpp
index 87a0388..ba4c456 100644
--- a/src/imports/pluginmain.cpp
+++ b/src/imports/pluginmain.cpp
@@ -31,6 +31,13 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+
+    \inqmlmodule QtOTAUpdate
+    \qmltype OTAClient
+    \instantiates QOTAClient
+*/
+
 static QObject *otaClientSingleton(QQmlEngine *qmlEngine, QJSEngine *jsEngine)
 {
     Q_UNUSED(qmlEngine);
diff --git a/src/lib/qotaclient.cpp b/src/lib/qotaclient.cpp
index d309334..eb0297f 100644
--- a/src/lib/qotaclient.cpp
+++ b/src/lib/qotaclient.cpp
@@ -233,6 +233,41 @@ QString QOTAClientPrivate::revision(QueryTarget target) const
     }
 }
 
+/*!
+    \class QOTAClient
+    \inmodule qtotaupdate
+    \brief Main interface to the OTA functionality.
+
+    This class provides API to perform 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.
+*/
+
+/*!
+    \fn void QOTAClient::fetchServerInfoFinished(bool success)
+
+    This is a notifier signal for fetchServerInfo(). The \a success argument
+    indicates whether the operation was successful.
+*/
+
+/*!
+    \fn void QOTAClient::updateFinished(bool success)
+
+    This is a notifier signal for update(). The \a success argument
+    indicates whether the operation was successful.
+*/
+
+/*!
+    \fn void QOTAClient::rollbackFinished(bool success)
+
+    This is a notifier signal for rollback(). The \a success argument
+    indicates whether the operation was successful.
+*/
+
 QOTAClient::QOTAClient(QObject *parent) : QObject(parent),
     d_ptr(new QOTAClientPrivate(this))
 {
@@ -255,6 +290,15 @@ QOTAClient::~QOTAClient()
     delete d_ptr;
 }
 
+/*!
+    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, see fetchServerInfoFinished().
+
+    \sa updateAvailable(), serverInfo()
+*/
 bool QOTAClient::fetchServerInfo() const
 {
     Q_D(const QOTAClient);
@@ -265,6 +309,13 @@ bool QOTAClient::fetchServerInfo() const
     return true;
 }
 
+/*!
+    Fetch an OTA update from a server and perform the system update.
+
+    This method is asynchronous and returns immediately, see updateFinished().
+
+    \sa fetchServerInfo(), updateAvailable(), restartRequired()
+*/
 bool QOTAClient::update() const
 {
     Q_D(const QOTAClient);
@@ -275,6 +326,13 @@ bool QOTAClient::update() const
     return true;
 }
 
+/*!
+    Rollback to the previous system version.
+
+    This method is asynchronous and returns immediately, see rollbackFinished().
+
+    \sa restartRequired()
+*/
 bool QOTAClient::rollback() const
 {
     Q_D(const QOTAClient);
@@ -285,24 +343,53 @@ bool QOTAClient::rollback() const
     return true;
 }
 
+/*!
+    \property QOTAClient::otaEnabled
+    \brief whether a device supports OTA updates.
+*/
 bool QOTAClient::otaEnabled() const
 {
     Q_D(const QOTAClient);
     return d->m_otaEnabled;
 }
 
+/*!
+    \property QOTAClient::initialized
+    \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
+    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()
+*/
 bool QOTAClient::initialized() const
 {
     Q_D(const QOTAClient);
     return d->m_initialized;
 }
 
+/*!
+    \property QOTAClient::error
+    \brief a string containing the last error occurred.
+*/
 QString QOTAClient::errorString() const
 {
     Q_D(const QOTAClient);
     return d->m_error;
 }
 
+/*!
+    \property QOTAClient::updateAvailable
+    \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().
+*/
 bool QOTAClient::updateAvailable() const
 {
     Q_D(const QOTAClient);
@@ -312,6 +399,14 @@ bool QOTAClient::updateAvailable() const
     return d->m_updateAvailable;
 }
 
+/*!
+    \property QOTAClient::restartRequired
+    \brief whether a reboot is required.
+
+    Holds a bool indicating whether a reboot is required. A reboot is required
+    after update() and rollback() to boot into the new default system.
+
+*/
 bool QOTAClient::restartRequired() const
 {
     Q_D(const QOTAClient);
@@ -321,65 +416,145 @@ bool QOTAClient::restartRequired() const
     return d->m_restartRequired;
 }
 
+/*!
+    \property QOTAClient::clientVersion
+    \brief a QString containing the booted system's version.
+
+    This is a convenience method.
+    \sa clientInfo()
+*/
 QString QOTAClient::clientVersion() const
 {
     return d_func()->version(QOTAClientPrivate::QueryTarget::Client);
 }
 
+/*!
+    \property QOTAClient::clientDescription
+    \brief a QString containing the booted system's description.
+
+    This is a convenience method.
+    \sa clientInfo()
+*/
 QString QOTAClient::clientDescription() const
 {
     return d_func()->description(QOTAClientPrivate::QueryTarget::Client);
 }
 
+/*!
+    \property QOTAClient::clientRevision
+    \brief a QString containing the booted system's revision.
+
+    A checksum in the OSTree repository.
+*/
 QString QOTAClient::clientRevision() const
 {
     return d_func()->revision(QOTAClientPrivate::QueryTarget::Client);
 }
 
+/*!
+    \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.
+*/
 QByteArray QOTAClient::clientInfo() const
 {
     return d_func()->info(QOTAClientPrivate::QueryTarget::Client);
 }
 
+/*!
+    \property QOTAClient::serverVersion
+    \brief a QString containing the system's version on a server.
+
+    This is a convenience method.
+    \sa serverInfo()
+*/
 QString QOTAClient::serverVersion() const
 {
     return d_func()->version(QOTAClientPrivate::QueryTarget::Server);
 }
 
+/*!
+    \property QOTAClient::serverDescription
+    \brief a QString containing the system's description on a server.
+
+    This is a convenience method.
+    \sa serverInfo()
+*/
 QString QOTAClient::serverDescription() const
 {
     return d_func()->description(QOTAClientPrivate::QueryTarget::Server);
 }
 
+/*!
+    \property QOTAClient::serverRevision
+    \brief a QString containing the system's revision on a server.
+
+    A checksum in the OSTree repository.
+*/
 QString QOTAClient::serverRevision() const
 {
     return d_func()->revision(QOTAClientPrivate::QueryTarget::Server);
 }
 
+/*!
+    \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.
+*/
 QByteArray QOTAClient::serverInfo() const
 {
     return d_func()->info(QOTAClientPrivate::QueryTarget::Server);
 }
 
+/*!
+    \property QOTAClient::rollbackVersion
+    \brief a QString containing the rollback system's version.
+
+    This is a convenience method.
+    \sa rollbackInfo()
+*/
 QString QOTAClient::rollbackVersion() const
 {
     return d_func()->version(QOTAClientPrivate::QueryTarget::Rollback);
 }
 
+/*!
+    \property QOTAClient::rollbackDescription
+    \brief a QString containing the rollback system's description.
+
+    This is a convenience method.
+    \sa rollbackInfo()
+*/
 QString QOTAClient::rollbackDescription() const
 {
     return d_func()->description(QOTAClientPrivate::QueryTarget::Rollback);
 }
 
+/*!
+    \property QOTAClient::rollbackRevision
+    \brief a QString containing the rollback system's revision.
+
+    A checksum in the OSTree repository.
+*/
 QString QOTAClient::rollbackRevision() const
 {
     return d_func()->revision(QOTAClientPrivate::QueryTarget::Rollback);
 }
 
+/*!
+    \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.
+*/
 QByteArray QOTAClient::rollbackInfo() const
 {
     return d_func()->info(QOTAClientPrivate::QueryTarget::Rollback);
 }
 
-
 QT_END_NAMESPACE
diff --git a/src/lib/qotaclient.h b/src/lib/qotaclient.h
index a1a2834..fbac67f 100644
--- a/src/lib/qotaclient.h
+++ b/src/lib/qotaclient.h
@@ -87,13 +87,13 @@ public:
     QByteArray rollbackInfo() const;
 
 Q_SIGNALS:
-    void initializationFinished();
     void serverInfoChanged();
     void rollbackInfoChanged();
     void updateAvailableChanged(bool available);
     void restartRequiredChanged(bool required);
     void errorOccurred(const QString &error);
 
+    void initializationFinished();
     void fetchServerInfoFinished(bool success);
     void updateFinished(bool success);
     void rollbackFinished(bool success);