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

[Cris Dywan]

Mark internal methods, mention model feature and document parameters

Mark internal methods, mention model feature and document parameters

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

PASSED: Continuous integration, rev:83
http://91.189.93.125:8080/job/u1db-qt-ci/10/
Executed test runs:
    SUCCESS: http://91.189.93.125:8080/job/u1db-qt-quantal-amd64-ci/10
    SUCCESS: http://91.189.93.125:8080/job/u1db-qt-raring-amd64-ci/10

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

review: Approve (continuous-integration)

[Cris Dywan (kalikiana)]

review: Approve

=== modified file 'documentation/u1db.qdocconf'
--- documentation/u1db.qdocconf	2013-04-22 10:35:32 +0000
+++ documentation/u1db.qdocconf	2013-04-22 12:57:29 +0000
@@ -11,6 +11,7 @@
 Cpp.ignoretokens = Q_DECL_EXPORT \
                    Q_PROPERTY \
                    QT_BEGIN_NAMESPACE_U1DB \
+                   Q_INVOKABLE \
                    
 defines = Q_QDOC
 Cpp.ignoredirectives = Q_ENUMS \

=== modified file 'src/database.cpp'
--- src/database.cpp	2013-04-22 10:35:32 +0000
+++ src/database.cpp	2013-04-22 12:57:29 +0000
@@ -39,8 +39,8 @@
     \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.
+    Database can be used as a QAbstractListModel, delegates will then have access to \a docId and \a contents
+    analogous to the properties of Document.
 */
 
 /*!
@@ -167,6 +167,7 @@
 }
 
 /*!
+    \internal
     Used to implement QAbstractListModel
     Implements the variables exposed to the Delegate in a model
     QVariant contents
@@ -185,6 +186,7 @@
 }
 
 /*!
+    \internal
     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.
@@ -199,6 +201,7 @@
 }
 
 /*!
+    \internal
     Used to implement QAbstractListModel
     The number of rows: the number of documents in the database.
  */
@@ -216,8 +219,9 @@
 }
 
 /*!
-    Same functionality as getDoc() except it won't set lastError() and it
+    Same functionality as Database::getDoc() except it won't set Database::lastError() and it
     doesn't implicitly try to initialize the underlying database.
+    \a docId must be a valid unique ID string
     Use cases: model implementations, Document::getContents()
  */
 QVariant
@@ -240,9 +244,9 @@
 }
 
 /*!
-    Returns the contents of a document by docId in a form that QML recognizes
+    Returns the contents of a document by \a docId in a form that QML recognizes
     as a Variant object, it's identical to Document::getContents() with the
-    same docId.
+    same \a docId.
  */
 QVariant
 Database::getDoc(const QString& docId)
@@ -280,52 +284,52 @@
 }
 
 /*!
-    Updates the existing contents of the document identified by docId if
+    Updates the existing \a contents of the document identified by \a docId if
     there's no error.
-    If no docId is given or docId is an empty string the contents will be
+    If no \a docId is given or \a docId is an empty string the \a 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)
+Database::putDoc(QVariant contents, const QString& docId)
 {
     if (!initializeIfNeeded())
         return -1;
 
-    QString docId(newOrEmptyDocId);
-    QVariant oldDoc = docId.isEmpty() ? QVariant() : getDocUnchecked(docId);
+    QString newOrEmptyDocId(docId);
+    QVariant oldDoc = newOrEmptyDocId.isEmpty() ? QVariant() : getDocUnchecked(newOrEmptyDocId);
     /* FIXME: Conflicts */
 
-    int newRev = increaseVectorClockRev(7/*newDoc.rev*/);
+    int newRev = increaseVectorClockRev(7/*contents.rev*/);
     QSqlQuery query(m_db.exec());
     if (oldDoc.isValid())
     {
         query.prepare("UPDATE document SET doc_rev=:docRev, content=:docJson WHERE doc_id = :docId");
-        query.bindValue(":docId", docId);
+        query.bindValue(":docId", newOrEmptyDocId);
         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);
+        QString json(QJsonDocument::fromVariant(contents).toJson());
+        query.bindValue(":docJson", json.isEmpty() ? contents : json);
         if (!query.exec())
-            return setError(QString("Failed to put/ update document %1: %2\n%3").arg(docId).arg(query.lastError().text()).arg(query.lastQuery())) ? -1 : -1;
+            return setError(QString("Failed to put/ update document %1: %2\n%3").arg(newOrEmptyDocId).arg(query.lastError().text()).arg(query.lastQuery())) ? -1 : -1;
         query.prepare("DELETE FROM document_fields WHERE doc_id = :docId");
-        query.bindValue(":docId", docId);
+        query.bindValue(":docId", newOrEmptyDocId);
         if (!query.exec())
-            return setError(QString("Failed to delete document field %1: %2\n%3").arg(docId).arg(query.lastError().text()).arg(query.lastQuery())) ? -1 : -1;
+            return setError(QString("Failed to delete document field %1: %2\n%3").arg(newOrEmptyDocId).arg(query.lastError().text()).arg(query.lastQuery())) ? -1 : -1;
     }
     else
     {
-        if (docId.isEmpty())
-            docId = QString("D-%1").arg(QUuid::createUuid().toString().mid(1).replace("}",""));
-        if (!QRegExp("^[a-zA-Z0-9.%_-]+$").exactMatch(docId))
-            return setError(QString("Invalid docID %1").arg(docId)) ? -1 : -1;
+        if (newOrEmptyDocId.isEmpty())
+            newOrEmptyDocId = QString("D-%1").arg(QUuid::createUuid().toString().mid(1).replace("}",""));
+        if (!QRegExp("^[a-zA-Z0-9.%_-]+$").exactMatch(newOrEmptyDocId))
+            return setError(QString("Invalid docID %1").arg(newOrEmptyDocId)) ? -1 : -1;
 
         query.prepare("INSERT INTO document (doc_id, doc_rev, content) VALUES (:docId, :docRev, :docJson)");
-        query.bindValue(":docId", docId);
+        query.bindValue(":docId", newOrEmptyDocId);
         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());
+        QJsonDocument json(QJsonDocument::fromVariant(contents));
+        query.bindValue(":docJson", json.isEmpty() ? contents : json.toJson());
         if (!query.exec())
             return setError(QString("Failed to put document %1: %2\n%3").arg(docId).arg(query.lastError().text()).arg(query.lastQuery())) ? -1 : -1;
     }
@@ -341,7 +345,7 @@
 
     documentCount = documents.count();
 
-    Q_EMIT docChanged(docId, newDoc);
+    Q_EMIT docChanged(newOrEmptyDocId, contents);
 
     return newRev;
 }
@@ -403,8 +407,8 @@
 }
 
 /*!
-   Stores a new index under the given name. An existing index won't be
-   replaced implicitly, an error will be set in that case.
+   Stores a new index under the given \a indexName, with \a expressions.
+   An existing index won't be replaced implicitly, an error will be set in that case.
  */
 QString
 Database::putIndex(const QString& indexName, QStringList expressions)
@@ -442,6 +446,7 @@
 
 /*!
    Gets the expressions saved with putIndex().
+   \a indexName: the unique name of an existing index
  */
 QStringList
 Database::getIndexExpressions(const QString& indexName)
@@ -464,6 +469,7 @@
 
 /*!
    Lists the index keys of an index created with putIndex().
+   \a indexName: the unique name of an existing index
  */
 QStringList
 Database::getIndexKeys(const QString& indexName)

=== modified file 'src/index.cpp'
--- src/index.cpp	2013-04-22 10:35:32 +0000
+++ src/index.cpp	2013-04-22 12:57:29 +0000
@@ -152,8 +152,7 @@
 }
 
 /*!
- * \brief Index::generateIndexResults
- *
+   \internal
  * Iterates through the documents stored in the database and creates the list of results based on the Index expressions.
  */
 
@@ -180,6 +179,9 @@
 
 }
 
+/*!
+    \internal
+ */
 void Index::clearResults()
 {
     m_results.clear();
@@ -187,8 +189,7 @@
 
 
 /*!
- * \brief Index::getAllResults
- * \return
+   \internal
  */
 
 QList<QVariantMap> Index::getAllResults(){
@@ -196,20 +197,14 @@
 }
 
 /*!
- * \brief Index::getResult
- * \param index
- * \return
+   \internal
  */
 QVariantMap Index::getResult(int index){
     return m_results[index];
 }
 
 /*!
- * \brief Index::appendResultsFromMap
- * \param fieldsList
- * \param current_section
- * \param current_field
- * \return
+   \internal
  *
  *This method is desinged to recursively iterate through a document, or section of a document, which represents a QVariantMap. As it iterates through the entire document, the method keeps track of the current index expression, and populates a local QVariantMap should the current expression be found in the Index's list of expressions.
  *
@@ -264,11 +259,7 @@
     return fieldsList;
 }
 /*!
- * \brief Index::getFieldsFromList
- * \param fieldsList
- * \param current_section
- * \param current_field
- * \return
+   \internal
  *
  *This recursive method is used in conjuntion with Index::appendResultsFromMap, to aid in iterating through a document when an embedded list is found.
  *

=== modified file 'src/query.cpp'
--- src/query.cpp	2013-04-22 11:19:36 +0000
+++ src/query.cpp	2013-04-22 12:57:29 +0000
@@ -39,7 +39,8 @@
     \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 can be used as a QAbstractListModel, delegates will then have access to \a docId and \a contents
+    analogous to the properties of Document.
 */
 
 Query::Query(QObject *parent) :
@@ -48,10 +49,7 @@
 }
 
 /*!
- * \brief Query::data
- * \param index
- * \param role
- * \return
+    \internal
  *Used to implement QAbstractListModel
  *Implements the variables exposed to the Delegate in a model
  */
@@ -74,6 +72,7 @@
 }
 
 /*!
+    \internal
     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.
@@ -88,6 +87,7 @@
 }
 
 /*!
+    \internal
     Used to implement QAbstractListModel
     The number of rows: the number of documents given by the query.
  */
@@ -97,12 +97,19 @@
     return m_hash.count();
 }
 
+/*!
+    Returns the Index used to query the database.
+ */
 Index*
 Query::getIndex()
 {
     return m_index;
 }
 
+/*!
+    Emitted whenever the index or documents change, and the results
+    need to be updated.
+ */
 void
 Query::onDataInvalidated()
 {
@@ -303,6 +310,9 @@
 
 }
 
+/*!
+    Returns the query used, in the form of a string, list or variant.
+ */
 QVariant
 Query::getQuery()
 {