Merge lp:~kalikiana/u1db-qt/trunk into lp:u1db-qt

[Cris Dywan]

qdoc for Database, Document, Index and Query

qdoc for Database, Document, Index and Query

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

FAILED: Continuous integration, rev:66
No commit message was specified in the merge proposal. Click on the following link and set the commit message (if you want a jenkins rebuild you need to trigger it yourself):
https://code.launchpad.net/~kalikiana/u1db-qt/trunk/+merge/156795/+edit-commit-message

http://91.189.93.125:8080/job/u1db-qt-ci/6/
Executed test runs:
    SUCCESS: http://91.189.93.125:8080/job/u1db-qt-quantal-amd64-ci/6
    SUCCESS: http://91.189.93.125:8080/job/u1db-qt-raring-amd64-ci/6

Click here to trigger a rebuild:
http://91.189.93.125:8080/job/u1db-qt-ci/6/rebuild

review: Needs Fixing (continuous-integration)

[Cris Dywan (kalikiana)]

review: Approve

[Ubuntu Phone Apps Jenkins Bot (ubuntu-phone-apps-jenkins-bot)]

review: Approve (continuous-integration)

=== modified file 'database.cpp'
--- database.cpp	2013-03-20 17:10:45 +0000
+++ database.cpp	2013-04-03 10:16:22 +0000
@@ -31,6 +31,19 @@
 
 QT_BEGIN_NAMESPACE_U1DB
 
+/*!
+    \class Database
+
+    \brief The Database class implements the on-disk storage of an individual
+    U1DB database.
+
+    The functional API can be used from C++ and Javascript, and is the basis of
+    the declarative API.
+*/
+
+/*!
+    A unique identifier for the state of synchronization
+ */
 QString
 Database::getReplicaUid()
 {
@@ -40,6 +53,10 @@
     return setError(QString("Failed to get replica UID: %1\n%2").arg(query.lastError().text()).arg(query.lastQuery())) ? QString() : QString();
 }
 
+/*!
+    Checks if the underlying SQLite database is ready to be used
+    Only to be used as a utility function by initializeIfNeeded()
+ */
 bool
 Database::isInitialized()
 {
@@ -49,6 +66,9 @@
     return query.next();
 }
 
+/*!
+    Describes the error as a string if the last operation failed.
+ */
 bool
 Database::setError(const QString& error)
 {
@@ -58,12 +78,22 @@
     return false;
 }
 
+/*!
+    Describes the error as a string if the last operation failed.
+ */
 QString
 Database::lastError()
 {
     return m_error;
 }
 
+/*!
+    Ensures that the underlying database works, or tries to set it up:
+
+    The SQlite backend is loaded - it's an optional Qt5 module and can fail
+    If @path is an existing database, it'll be opened
+    For a new database, the default schema will be applied
+ */
 bool
 Database::initializeIfNeeded(const QString& path)
 {
@@ -115,6 +145,11 @@
     initializeIfNeeded();
 }
 
+/*!
+    Used to implement QAbstractListModel
+    Returns docId matching the given row index
+    assuming all documents are ordered consistently
+ */
 QString
 Database::getDocIdByRow(int row) const
 {
@@ -129,6 +164,13 @@
     return QString();
 }
 
+/*!
+    Used to implement QAbstractListModel
+    Implements the variables exposed to the Delegate in a model
+    QVariant contents
+    QString docId
+    int index (built-in)
+ */
 QVariant
 Database::data(const QModelIndex & index, int role) const
 {
@@ -140,6 +182,11 @@
     return QVariant();
 }
 
+/*!
+    Used to implement QAbstractListModel
+    Defines \b{contents} and \b{docId} as variables exposed to the Delegate in a model
+    \b{index} is supported out of the box.
+ */
 QHash<int, QByteArray>
 Database::roleNames() const
 {
@@ -149,6 +196,10 @@
     return roles;
 }
 
+/*!
+    Used to implement QAbstractListModel
+    The number of rows: the number of documents in the database.
+ */
 int
 Database::rowCount(const QModelIndex & parent) const
 {
@@ -162,6 +213,11 @@
     return query.value("count").toInt();
 }
 
+/*!
+    Same functionality as getDoc() except it won't set lastError() and it
+    doesn't implicitly try to initialize the underlying database.
+    Use cases: model implementations, Document::getContents()
+ */
 QVariant
 Database::getDocUnchecked(const QString& docId) const
 {
@@ -173,6 +229,7 @@
     query.bindValue(":docId", docId);
     if (query.exec() && query.next())
     {
+        // Convert JSON string to the Variant that QML expects
         QJsonDocument json(QJsonDocument::fromJson(query.value("content").toByteArray()));
         Q_EMIT docLoaded(docId, json.object().toVariantMap());
         return json.object().toVariantMap();
@@ -180,6 +237,11 @@
     return QVariant();
 }
 
+/*!
+    Returns the contents of a document by docId in a form that QML recognizes
+    as a Variant object, it's identical to Document::getContents() with the
+    same docId.
+ */
 QVariant
 Database::getDoc(const QString& docId)
 {
@@ -199,6 +261,7 @@
         {
             if (query.value("conflicts").toInt() > 0)
                 setError(QString("Conflicts in %1").arg(docId));
+            // Convert JSON string to the Variant that QML expects
             QJsonDocument json(QJsonDocument::fromJson(query.value("content").toByteArray()));
             Q_EMIT docLoaded(docId, json.object().toVariantMap());
             return json.object().toVariantMap();
@@ -214,6 +277,13 @@
     return oldRev;
 }
 
+/*!
+    Updates the existing contents of the document identified by docId if
+    there's no error.
+    If no docId is given or docId is an empty string the contents will be
+    stored under an autogenerated name.
+    Returns the new revision of the document, or -1 on failure.
+ */
 int
 Database::putDoc(QVariant newDoc, const QString& newOrEmptyDocId)
 {
@@ -231,6 +301,7 @@
         query.prepare("UPDATE document SET doc_rev=:docRev, content=:docJson WHERE doc_id = :docId");
         query.bindValue(":docId", docId);
         query.bindValue(":docRev", newRev);
+        // Parse Variant from QML as JsonDocument, fallback to string
         QString json(QJsonDocument::fromVariant(newDoc).toJson());
         query.bindValue(":docJson", json.isEmpty() ? newDoc : json);
         if (!query.exec())
@@ -250,6 +321,7 @@
         query.prepare("INSERT INTO document (doc_id, doc_rev, content) VALUES (:docId, :docRev, :docJson)");
         query.bindValue(":docId", docId);
         query.bindValue(":docRev", newRev);
+        // Parse Variant from QML as JsonDocument, fallback to string
         QJsonDocument json(QJsonDocument::fromVariant(newDoc));
         query.bindValue(":docJson", json.isEmpty() ? newDoc : json.toJson());
         if (!query.exec())
@@ -290,6 +362,13 @@
     return setError(QString("Failed to list documents: %1\n%2").arg(query.lastError().text()).arg(query.lastQuery())) ? list : list;
 }
 
+/*!
+    A relative filename or absolute path advises the database to store documents
+    and indexes persistently on disk. Internally, an SQlite database is written.
+
+    If no path is set, as is the default, all database contents are written in
+    memory only. The same affect can be achieved by passing the string ":memory:".
+ */
 void
 Database::setPath(const QString& path)
 {
@@ -306,12 +385,20 @@
     Q_EMIT pathChanged(path);
 }
 
+/*!
+   The persistent storage location if set. By default the database is only
+   storted in memory. See setPath().
+ */
 QString
 Database::getPath()
 {
     return m_path;
 }
 
+/*!
+   Stores a new index under the given name. An existing index won't be
+   replaced implicitly, an error will be set in that case.
+ */
 QString
 Database::putIndex(const QString& indexName, QStringList expressions)
 {
@@ -346,6 +433,9 @@
     return QString();
 }
 
+/*!
+   Gets the expressions saved with putIndex().
+ */
 QStringList
 Database::getIndexExpressions(const QString& indexName)
 {
@@ -365,6 +455,9 @@
     return expressions;
 }
 
+/*!
+   Lists the index keys of an index created with putIndex().
+ */
 QStringList
 Database::getIndexKeys(const QString& indexName)
 {
 
=== modified file 'document.cpp'
--- document.cpp	2013-03-06 12:06:56 +0000
+++ document.cpp	2013-04-03 10:16:22 +0000
@@ -30,6 +30,15 @@
 
 QT_BEGIN_NAMESPACE_U1DB
 
+/*!
+    \class Document
+
+    \brief The Document class proxies a single document stored in the Database.
+
+    This is the declarative API equivalent of Database::putDoc() and
+    Database::getDoc().
+*/
+
 Document::Document(QObject *parent) :
     QObject(parent), m_database(0), m_create(false)
 {
@@ -61,6 +70,10 @@
     }
 }
 
+/*!
+    The database is used to lookup the contents of the document, reflecting
+    changes done to it and conversely changes are saved to the database.
+ */
 void
 Document::setDatabase(Database* database)
 {
@@ -90,6 +103,11 @@
     return m_docId;
 }
 
+/*!
+    The docId can be that of an existing document in the database and
+    will determine what getContents() returns.
+    If no such documents exists, setDefaults() can be used to supply a preset.
+ */
 void
 Document::setDocId(const QString& docId)
 {
@@ -112,6 +130,10 @@
     return m_create;
 }
 
+/*!
+    If create is true, docId is not empty and no document with the same docId
+    exists, defaults will be used to store the document.
+ */
 void
 Document::setCreate(bool create)
 {
@@ -131,6 +153,12 @@
     return m_defaults;
 }
 
+/*!
+    The default contents of the document, which are used only if
+    create is true, docId is not empty and no document with the same
+    docId exists in the database yet.
+    If the defaults change, it's up to the API user to handle it.
+ */
 void
 Document::setDefaults(QVariant defaults)
 {
@@ -144,12 +172,20 @@
         m_database->putDoc(m_defaults, m_docId);
 }
 
+/*!
+    The contents of the document, as set via setContents() or stored in
+    the database via Database::putDoc().
+    onContentsChanged() can be used to monitor changes.
+ */
 QVariant
 Document::getContents()
 {
     return m_contents;
 }
 
+/*!
+    Updates the contents of the document. A valid docId must be set.
+ */
 void
 Document::setContents(QVariant contents)
 {
 
=== modified file 'index.cpp'
--- index.cpp	2013-02-28 17:59:51 +0000
+++ index.cpp	2013-04-03 10:16:22 +0000
@@ -30,6 +30,17 @@
 
 QT_BEGIN_NAMESPACE_U1DB
 
+/*!
+    \class Index
+
+    \brief The Index class defines an index to be stored in the database and
+    queried using Query. Changes in documents affected by the index also update
+    the index in the database.
+
+    This is the declarative API equivalent of Database::putIndex() and
+    Database::getIndexExpressions().
+*/
+
 Index::Index(QObject *parent) :
     QObject(parent), m_database(0)
 {
@@ -53,6 +64,11 @@
     Q_EMIT dataInvalidated();
 }
 
+/*!
+    Sets the Database to lookup documents from and store the index in. The
+    dataInvalidated() signal will be emitted on all changes that could affect
+    the index.
+ */
 void
 Index::setDatabase(Database* database)
 {
@@ -80,6 +96,10 @@
     return m_name;
 }
 
+/*!
+    Sets the name used. Both an expression and a name must be specified
+    for an index to be created.
+ */
 void
 Index::setName(const QString& name)
 {
@@ -102,6 +122,10 @@
     return m_expression;
 }
 
+/*!
+    Sets the expression used. Both an expression and a name must be specified
+    for an index to be created.
+ */
 void
 Index::setExpression(QStringList expression)
 {
 
=== modified file 'query.cpp'
--- query.cpp	2013-02-28 17:59:51 +0000
+++ query.cpp	2013-04-03 10:16:22 +0000
@@ -31,11 +31,27 @@
 
 QT_BEGIN_NAMESPACE_U1DB
 
+/*!
+    \class Query
+
+    \brief The Query class generates a filtered list of documents based on either
+    a query or a range, and using the given Index.
+
+    This is the declarative API equivalent of FIXME
+*/
+
 Query::Query(QObject *parent) :
     QAbstractListModel(parent), m_index(0)
 {
 }
 
+/*!
+    Used to implement QAbstractListModel
+    Implements the variables exposed to the Delegate in a model
+    QVariant contents
+    QString docId
+    int index (built-in)
+ */
 QVariant
 Query::data(const QModelIndex & index, int role) const
 {
@@ -44,13 +60,21 @@
     {
         Database* db(m_index->getDatabase());
         if (db)
+        {
+            qDebug() << "Query::getData" << docId;
             return db->getDocUnchecked(docId);
+        }
     }
     if (role == 1) // docId
         return docId;
     return QVariant();
 }
 
+/*!
+    Used to implement QAbstractListModel
+    Defines \b{contents} and \b{docId} as variables exposed to the Delegate in a model
+    \b{index} is supported out of the box.
+ */
 QHash<int, QByteArray>
 Query::roleNames() const
 {
@@ -60,6 +84,10 @@
     return roles;
 }
 
+/*!
+    Used to implement QAbstractListModel
+    The number of rows: the number of documents given by the query.
+ */
 int
 Query::rowCount(const QModelIndex & parent) const
 {
@@ -82,6 +110,10 @@
     // TODO
 }
 
+/*!
+    Sets the Index to use. The index must have a valid name and index expressions,
+    then either a range or query can be set.
+ */
 void
 Query::setIndex(Index* index)
 {
@@ -103,6 +135,10 @@
     return m_query;
 }
 
+/*!
+    Sets a range, such as ['match', false].
+    Only one of query and range is used - setting range unsets the query.
+ */
 void
 Query::setQuery(QVariant query)
 {
@@ -123,6 +159,10 @@
     return m_range;
 }
 
+/*!
+    Sets a range, such as [['a', 'b'], ['*']].
+    Only one of query and range is used - setting range unsets the query.
+ */
 void
 Query::setRange(QVariant range)
 {