uonedb-qt team mailing list archive

[Christian Dywan <christian.dywan@xxxxxxxxxxxxx>]

Christian Dywan has proposed merging lp:~kalikiana/u1db-qt/trunk into lp:u1db-qt.

Requested reviews:
  U1DB Qt developers (uonedb-qt)

For more details, see:
https://code.launchpad.net/~kalikiana/u1db-qt/trunk/+merge/156580

Add qtdoc comments to document Database class
-- 
https://code.launchpad.net/~kalikiana/u1db-qt/trunk/+merge/156580
Your team U1DB Qt developers is requested to review the proposed merge of lp:~kalikiana/u1db-qt/trunk into lp:u1db-qt.

=== modified file 'database.cpp'
--- database.cpp	2013-03-20 17:10:45 +0000
+++ database.cpp	2013-04-02 14:37:30 +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)
 {