uonedb-qt team mailing list archive
-
uonedb-qt team
-
Mailing list archive
-
Message #00107
[Merge] lp:~kalikiana/u1db-qt/docf into lp:u1db-qt
Christian Dywan has proposed merging lp:~kalikiana/u1db-qt/docf into lp:u1db-qt.
Commit message:
Mark internal methods, mention model feature and document parameters
Requested reviews:
U1DB Qt developers (uonedb-qt)
For more details, see:
https://code.launchpad.net/~kalikiana/u1db-qt/docf/+merge/160097
Mark internal methods, mention model feature and document parameters
--
https://code.launchpad.net/~kalikiana/u1db-qt/docf/+merge/160097
Your team U1DB Qt developers is requested to review the proposed merge of lp:~kalikiana/u1db-qt/docf into lp:u1db-qt.
=== 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()
{
Follow ups