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

[Christian Dywan]

Port qdoc syntax to QML annotations

This gets us QML docs, including a few tweaks to ensure each has one example at the top, using highlighting and identifier linking. Behind each component a link is available to reveal the C++ version.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:113
http://jenkins.qa.ubuntu.com/job/u1db-qt-ci/40/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/u1db-qt-precise-amd64-ci/40/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/u1db-qt-saucy-amd64-ci/42/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/u1db-qt-trusty-amd64-ci/20/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/u1db-qt-trusty-armhf-ci/20/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/u1db-qt-ci/40/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:117
http://jenkins.qa.ubuntu.com/job/u1db-qt-ci/57/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/u1db-qt-vivid-amd64-ci/4
    SUCCESS: http://jenkins.qa.ubuntu.com/job/u1db-qt-vivid-armhf-ci/4

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/u1db-qt-ci/57/rebuild

review: Approve (continuous-integration)

[Marco Trevisan (Treviño) (3v1n0)]

Looks good... Added two small comments, just to stay in sync with the recent approved changes...

review: Approve

[lp:~kalikiana/u1db-qt/qmlDocs]

118. By Christian Dywan on 2015-03-24

Clarify path behavior documentation

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:118
http://jenkins.qa.ubuntu.com/job/u1db-qt-ci/67/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/u1db-qt-vivid-amd64-ci/14
    SUCCESS: http://jenkins.qa.ubuntu.com/job/u1db-qt-vivid-armhf-ci/14

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/u1db-qt-ci/67/rebuild

review: Approve (continuous-integration)

=== modified file 'documentation/u1db.qdocconf'
--- documentation/u1db.qdocconf	2013-09-06 10:00:36 +0000
+++ documentation/u1db.qdocconf	2015-03-24 19:42:30 +0000
@@ -5,12 +5,7 @@
 
 sourcedirs = ../src \
              ../documentation
-headers = ../src/database.h \
-          ../src/document.h \
-          ../src/index.h \
-          ../src/query.h \
-          ../src/synchronizer.h \
-          ../src/global.h
+headerdirs = ../src/
 Cpp.ignoretokens = Q_DECL_EXPORT \
                    Q_PROPERTY \
                    QT_BEGIN_NAMESPACE_U1DB \

=== modified file 'src/database.cpp'
--- src/database.cpp	2015-02-19 10:37:54 +0000
+++ src/database.cpp	2015-03-24 19:42:30 +0000
@@ -17,7 +17,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include <QDebug>
 #include <QSqlQuery>
 #include <QFile>
 #include <QFileInfo>
@@ -63,16 +62,41 @@
 /*!
     \class Database
     \inmodule U1Db
-    \ingroup modules
+    \ingroup cpp
 
-    \brief The Database class implements the on-disk storage of an individual
-    U1DB database.
+    \brief The Database class implements on-disk storage for documents and indexes.
 
     Database can be used as a QAbstractListModel, delegates will then have access to \a docId and \a contents
     analogous to the properties of Document.
 */
 
 /*!
+    \qmltype Database
+    \instantiates Database
+    \inqmlmodule U1Db 1.0
+    \ingroup modules
+
+    \brief Database implements on-disk storage for documents and indexes.
+
+    In a ListView the Database can be used as a model which includes all documents
+    in the database. For listing only a subset of documents Query can be used.
+
+    \qml
+    ListView {
+        model: Database {
+            id: myDatabase
+        }
+        delegate: ListItem.Subtitled {
+            text: docId
+            subText: contents.color
+        }
+    }
+    \endqml
+
+    \sa Query
+*/
+
+/*!
     A unique identifier for the state of synchronization
  */
 QString
@@ -110,7 +134,10 @@
 }
 
 /*!
-    \property Database::error
+    \qmlproperty string Database::error
+    The last error as a string if the last operation failed.
+ */
+/*!
     The last error as a string if the last operation failed.
  */
 QString
@@ -335,10 +362,16 @@
 
 
 /*!
+    \qmlmethod Variant Database::getDoc(string)
     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 \a docId.
  */
+/*!
+ *  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 \a docId.
+ */
 QVariant
 Database::getDoc(const QString& docId)
 {
@@ -513,7 +546,6 @@
 
 /*!
  * \internal
- * \brief Database::updateDocRevisionNumber
  *
  * Whenever a document as added or modified it needs a new revision number.
  *
@@ -614,6 +646,14 @@
 }
 
 /*!
+    \qmlmethod string Database::putDoc(var, string)
+    Updates the existing \a contents of the document identified by \a docId if
+    there's no error.
+    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.
+ */
+/*!
     Updates the existing \a contents of the document identified by \a docId if
     there's no error.
     If no \a docId is given or \a docId is an empty string the \a contents will be
@@ -687,6 +727,10 @@
 }
 
 /*!
+    \qmlmethod void Database::deleteDoc(string)
+    Deletes the document identified by \a docId.
+ */
+/*!
     Deletes the document identified by \a docId.
  */
 void
@@ -710,6 +754,10 @@
 
 
 /*!
+    \qmlmethod list<string> Database::listDocs()
+    Returns a list of all stored documents by their docId.
+ */
+/*!
     Returns a list of all stored documents by their docId.
  */
 QList<QString>
@@ -737,11 +785,17 @@
 }
 
 /*!
-    \property Database::path
-    A relative filename can be given to store the database in an app-specific
-    writable folder. This is recommended as it ensures to work with confinement.
-    If more control is needed absolute paths can be used.
-    By default everything is stored in memory.
+    \qmlproperty string Database::path
+    A relative \a path can be given to store the database in an app-specific
+    writable folder. This is recommended as it ensures to work with confinement.
+    If more control is needed absolute paths or local file URIs can be used.
+    By default or if the path is empty everything is stored in memory.
+ */
+/*!
+    A relative \a path can be given to store the database in an app-specific
+    writable folder. This is recommended as it ensures to work with confinement.
+    If more control is needed absolute paths or local file URIs can be used.
+    By default or if the path is empty everything is stored in memory.
  */
 void
 Database::setPath(const QString& path)
@@ -759,10 +813,7 @@
 }
 
 /*!
- * \brief Database::getPath
- *
- * Simply returns the path of the database.
- *
+ * Returns the path of the database.
  */
 QString
 Database::getPath()

=== modified file 'src/database.h'
--- src/database.h	2014-01-24 11:13:35 +0000
+++ src/database.h	2015-03-24 19:42:30 +0000
@@ -31,7 +31,9 @@
 
 class Q_DECL_EXPORT Database : public QAbstractListModel {
     Q_OBJECT
+    /*! path */
     Q_PROPERTY(QString path READ getPath WRITE setPath NOTIFY pathChanged)
+    /*! error */
     Q_PROPERTY(QString error READ lastError NOTIFY errorChanged)
 public:
     Database(QObject* parent = 0);
@@ -65,7 +67,15 @@
     QMap<QString,QVariant> getSyncLogInfo(QMap<QString,QVariant> lastSyncInformation, QString uid, QString prefix);
 
 Q_SIGNALS:
+    /*!
+        \signal Database::pathChanged
+        The database path changed - the empty string means it's in-memory only.
+     */
     void pathChanged(const QString& path);
+    /*!
+        \signal Database::errorChanged
+        An error occurred. Use lastError() to check it.
+     */
     void errorChanged(const QString& error);
     /*!
         A document's contents were modified.

=== modified file 'src/document.cpp'
--- src/document.cpp	2015-02-19 10:37:54 +0000
+++ src/document.cpp	2015-03-24 19:42:30 +0000
@@ -17,14 +17,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include <QDebug>
-#include <QSqlQuery>
-#include <QFile>
-#include <QSqlError>
-#include <QUuid>
-#include <QStringList>
-#include <QJsonDocument>
-
 #include "document.h"
 #include "private.h"
 
@@ -33,12 +25,34 @@
 /*!
     \class Document
     \inmodule U1db
+    \ingroup cpp
+
+    \brief The Document class proxies a single document stored in the Database.
+*/
+
+
+/*!
+    \qmltype Document
+    \instantiates Document
+    \inqmlmodule U1db 1.0
     \ingroup modules
 
-    \brief The Document class proxies a single document stored in the Database.
+    \brief Document proxies a single document stored in the Database.
 
     This is the declarative API equivalent of Database::putDoc() and
     Database::getDoc().
+
+    \qml
+    Document {
+        docId: 'myId'
+        defaults: {
+            color: 'blue'
+        }
+        create: true
+    }
+    \endqml
+
+    \sa Database
 */
 
 /*!
@@ -50,6 +64,9 @@
 {
 }
 
+/*!
+   Returns the \l Database.
+ */
 Database*
 Document::getDatabase()
 {
@@ -77,8 +94,7 @@
 }
 
 /*!
-    \property Document::database
-    The database is used to lookup the contents of the document, reflecting
+    The \a database is used to lookup the contents of the document, reflecting
     changes done to it and conversely changes are saved to the database.
  */
 void
@@ -104,6 +120,9 @@
     Q_EMIT databaseChanged(database);
 }
 
+/*!
+   Returns the docId.
+ */
 QString
 Document::getDocId()
 {
@@ -111,11 +130,16 @@
 }
 
 /*!
-    \property Document::docId
+    \qmlproperty string Document::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.
  */
+/*!
+    The \a 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)
 {
@@ -132,6 +156,9 @@
     }
 }
 
+/*!
+    Returns whether the document will be newly created if it doesn't exist.
+ */
 bool
 Document::getCreate()
 {
@@ -139,8 +166,12 @@
 }
 
 /*!
-    \property Document::create
-    If create is true, docId is not empty and no document with the same docId
+    \qmlproperty bool Document::create
+    If \a create is true, docId is not empty and no document with the same docId
+    exists, defaults will be used to store the document.
+ */
+/*!
+    If \a create is true, docId is not empty and no document with the same docId
     exists, defaults will be used to store the document.
  */
 void
@@ -156,6 +187,10 @@
         m_database->putDoc(m_defaults, m_docId);
 }
 
+/*!
+    Returns the defaults to be used when the document is newly created
+    because it doesn't exist, if create is true.
+ */
 QVariant
 Document::getDefaults()
 {
@@ -163,11 +198,17 @@
 }
 
 /*!
-    \property Document::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.
+    \qmlproperty Variant Document::content
+    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 \a defaults change, it's up to the API user to handle it.
+ */
+/*!
+    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 \a defaults change, it's up to the API user to handle it.
  */
 void
 Document::setDefaults(QVariant defaults)
@@ -185,6 +226,9 @@
         m_database->putDoc(m_defaults, m_docId);
 }
 
+/*!
+    Returns the current contents of the document.
+ */
 QVariant
 Document::getContents()
 {
@@ -192,8 +236,11 @@
 }
 
 /*!
-    \property Document::contents
-    Updates the contents of the document. A valid docId must be set.
+    \qmlproperty Variant Document::contents
+    Updates the \a contents of the document. A valid docId must be set.
+ */
+/*!
+    Updates the \a contents of the document. A valid docId must be set.
  */
 void
 Document::setContents(QVariant contents)

=== modified file 'src/document.h'
--- src/document.h	2013-04-23 15:17:24 +0000
+++ src/document.h	2015-03-24 19:42:30 +0000
@@ -21,7 +21,6 @@
 #define U1DB_DOCUMENT_H
 
 #include <QtCore/QObject>
-#include <QSqlDatabase>
 #include <QVariant>
 
 #include "database.h"
@@ -31,13 +30,18 @@
 class Q_DECL_EXPORT Document : public QObject {
     Q_OBJECT
 #ifdef Q_QDOC
+    /*! database */
     Q_PROPERTY(Database* database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
 #else
     Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Database*) database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
 #endif
+    /*! docId */
     Q_PROPERTY(QString docId READ getDocId WRITE setDocId NOTIFY docIdChanged)
+    /*! create */
     Q_PROPERTY(bool create READ getCreate WRITE setCreate NOTIFY createChanged)
+    /*! defaults */
     Q_PROPERTY(QVariant defaults READ getDefaults WRITE setDefaults NOTIFY defaultsChanged)
+    /*! contents */
     Q_PROPERTY(QVariant contents READ getContents WRITE setContents NOTIFY contentsChanged)
 public:
     Document(QObject* parent = 0);
@@ -53,10 +57,25 @@
     QVariant getContents();
     void setContents(QVariant contents);
 Q_SIGNALS:
+    /*!
+        The database changed.
+     */
     void databaseChanged(Database* database);
+    /*!
+        The docId changed.
+     */
     void docIdChanged(const QString& docId);
+    /*!
+        The create flag changed.
+     */
     void createChanged(bool create);
+    /*!
+        The default contents changed.
+     */
     void defaultsChanged(QVariant defaults);
+    /*!
+        The current contents of the document changed.
+     */
     void contentsChanged(QVariant contents);
 private:
     Q_DISABLE_COPY(Document)

=== modified file 'src/index.cpp'
--- src/index.cpp	2014-01-31 19:20:07 +0000
+++ src/index.cpp	2015-03-24 19:42:30 +0000
@@ -17,13 +17,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include <QDebug>
-#include <QSqlQuery>
-#include <QFile>
-#include <QSqlError>
-#include <QUuid>
 #include <QStringList>
-#include <QJsonDocument>
 
 #include "index.h"
 #include "private.h"
@@ -32,15 +26,33 @@
 
 /*!
     \class Index
-    \inmodule U1Db
-    \ingroup modules
+    \inmodule U1db
+    \ingroup cpp
 
     \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().
+*/
+
+/*!
+    \qmltype Index
+    \instantiates Index
+    \inqmlmodule U1db 1.0
+    \ingroup modules
+
+    \brief An Index defines what fields can be filtered using Query.
+
+    Documents in the database will be included if they contain all fields in the expression.
+
+    \qml
+    Index {
+        database: myDatabase
+        name: 'colorIndex'
+        expression: [ 'color' ]
+    }
+    \endqml
+
+    \sa Query
 */
 
 /*!
@@ -52,6 +64,9 @@
 {
 }
 
+/*!
+    Returns the \l Database to lookup documents from and store the index in.
+ */
 Database*
 Index::getDatabase()
 {
@@ -71,11 +86,16 @@
 }
 
 /*!
-    \property Index::database
+    \qmlproperty Database Index::database
     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.
  */
+/*!
+    Sets the \a 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)
 {
@@ -98,6 +118,9 @@
 
 }
 
+/*!
+    Returns the name of the index. Both name and expression must be specified.
+ */
 QString
 Index::getName()
 {
@@ -105,10 +128,14 @@
 }
 
 /*!
-    \property Index::name
+    \qmlproperty string Index::name
     Sets the name used. Both an expression and a name must be specified
     for an index to be created.
  */
+/*!
+    Sets the \a name used. Both an expression and a name must be specified
+    for an index to be created.
+ */
 void
 Index::setName(const QString& name)
 {
@@ -125,6 +152,9 @@
     Q_EMIT nameChanged(name);
 }
 
+/*!
+    Returns the expression of the index. Both name and expression must be specified.
+ */
 QStringList
 Index::getExpression()
 {
@@ -132,12 +162,17 @@
 }
 
 /*!
-    \property Index::expression
+    \qmlproperty list<string> Index::expression
     Sets the expression used. Both an expression and a name must be specified
     for an index to be created.
 
     Also starts the process of creating the Index result list, which can then be queried or populate the Query model as is.
+ */
+/*!
+    Sets the \a expression used. Both an expression and a name must be specified
+    for an index to be created.
 
+    Also starts the process of creating the Index result list, which can then be queried or populate the Query model as is.
  */
 void
 Index::setExpression(QStringList expression)
@@ -189,7 +224,6 @@
 /*!
    \internal
  */
-
 QList<QVariantMap> Index::getAllResults(){
     generateIndexResults();
     return m_results;
@@ -205,7 +239,6 @@
  */
 QStringList Index::appendResultsFromMap(QString docId, QStringList fieldsList, QVariantMap current_section, QString current_field)
 {
-
     QMapIterator<QString, QVariant> i(current_section);
 
     QString original_field = current_field;
@@ -259,8 +292,6 @@
  *This recursive method is used in conjuntion with Index::appendResultsFromMap, to aid in iterating through a document when an embedded list is found.
  *
  */
-
-
 QStringList Index::getFieldsFromList(QString docId, QStringList fieldsList, QVariantList current_section, QString current_field)
 {
 

=== modified file 'src/index.h'
--- src/index.h	2013-04-25 13:38:33 +0000
+++ src/index.h	2015-03-24 19:42:30 +0000
@@ -21,7 +21,6 @@
 #define U1DB_INDEX_H
 
 #include <QtCore/QObject>
-#include <QSqlDatabase>
 #include <QStringList>
 
 #include "database.h"
@@ -31,11 +30,14 @@
 class Q_DECL_EXPORT Index : public QObject {
     Q_OBJECT
 #ifdef Q_QDOC
+    /*! database */
     Q_PROPERTY(Database* database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
 #else
     Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Database*) database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
 #endif
+    /*! name */
     Q_PROPERTY(QString name READ getName WRITE setName NOTIFY nameChanged)
+    /*! expression */
     Q_PROPERTY(QStringList expression READ getExpression WRITE setExpression NOTIFY expressionChanged)
 public:
     Index(QObject* parent = 0);
@@ -49,8 +51,17 @@
     QList<QVariantMap> getAllResults();
 
 Q_SIGNALS:
+    /*!
+        The database changed.
+     */
     void databaseChanged(Database* database);
+    /*!
+        The index name changed.
+     */
     void nameChanged(const QString& name);
+    /*!
+        The index expression changed.
+     */
     void expressionChanged(QVariant expression);
     /*!
         The database, an indexed document or the expressions changed.

=== modified file 'src/query.cpp'
--- src/query.cpp	2014-03-13 19:31:58 +0000
+++ src/query.cpp	2015-03-24 19:42:30 +0000
@@ -17,13 +17,7 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include <QDebug>
-#include <QSqlQuery>
-#include <QFile>
-#include <QSqlError>
-#include <QUuid>
 #include <QStringList>
-#include <QJsonDocument>
 
 #include "query.h"
 #include "database.h"
@@ -34,12 +28,42 @@
 /*!
     \class Query
     \inmodule U1db
-    \ingroup modules
+    \ingroup cpp
 
     \brief The Query class generates a filtered list of documents based on a query using the given Index.
 
     Query can be used as a QAbstractListModel, delegates will then have access to \a docId and \a contents
     analogous to the properties of Document.
+ */
+
+/*!
+    \qmltype Query
+    \instantiates Query
+    \inqmlmodule U1db 1.0
+    \ingroup modules
+
+    \brief Query filters documents based on the query and index.
+
+    In a ListView the Query can be used as a model.
+
+    \qml
+    ListView {
+        model: Query {
+            index: Index {
+                name: 'colorIndex'
+                expression: [ 'color' ]
+                database: myDatabase
+            }
+            query: [ 'blue' ]
+        }
+        delegate: ListItem.Subtitled {
+            text: docId
+            subText: contents.color
+        }
+    }
+    \endqml
+
+    \sa Index
 */
 
 /*!
@@ -93,6 +117,9 @@
     return m_results.count();
 }
 
+/*!
+    FIXME
+ */
 Index*
 Query::getIndex()
 {
@@ -287,10 +314,13 @@
 }
 
 /*!
-    \property Query::index
-    Sets the Index to use. The index must have a valid name and index expressions.
+    \qmlproperty Index Query::index
+    Sets the Index to use. \a index must have a valid name and index expressions.
     If no query is set, the default is all results of the index.
  */
+/*!
+    FIXME \a index
+ */
 void
 Query::setIndex(Index* index)
 {
@@ -305,11 +335,12 @@
     }
     Q_EMIT indexChanged(index);
 
-
     onDataInvalidated();
-
 }
 
+/*!
+    FIXME
+ */
 QVariant
 Query::getQuery()
 {
@@ -317,11 +348,14 @@
 }
 
 /*!
-    \property Query::query
+    \qmlproperty Variant Query::query
     A query in one of the allowed forms:
     'value', ['value'] or [{'sub-field': 'value'}].
     The default is equivalent to '*'.
  */
+/*!
+    FIXME \a query
+ */
 void
 Query::setQuery(QVariant query)
 {
@@ -334,9 +368,12 @@
 }
 
 /*!
-    \property Query::documents
+    \qmlproperty list<string> Query::documents
     The docId's of all matched documents.
  */
+/*!
+    FIXME
+ */
 QStringList
 Query::getDocuments()
 {
@@ -344,9 +381,12 @@
 }
 
 /*!
-    \property Query::results
+    \qmlproperty list<Variant> Query::results
     The results of the query as a list.
  */
+/*!
+    FIXME
+ */
 QList<QVariant>
 Query::getResults()
 {

=== modified file 'src/query.h'
--- src/query.h	2014-03-07 17:54:07 +0000
+++ src/query.h	2015-03-24 19:42:30 +0000
@@ -30,12 +30,16 @@
 class Q_DECL_EXPORT Query : public QAbstractListModel {
     Q_OBJECT
 #ifdef Q_QDOC
+    /*! index */
     Q_PROPERTY(Index* index READ getIndex WRITE setIndex NOTIFY indexChanged)
 #else
     Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Index*) index READ getIndex WRITE setIndex NOTIFY indexChanged)
 #endif
+    /*! query */
     Q_PROPERTY(QVariant query READ getQuery WRITE setQuery NOTIFY queryChanged)
+    /*! documents */
     Q_PROPERTY(QStringList documents READ getDocuments NOTIFY documentsChanged)
+    /*! results */
     Q_PROPERTY(QList<QVariant> results READ getResults NOTIFY resultsChanged)
 public:
     Query(QObject* parent = 0);
@@ -55,9 +59,21 @@
     void resetModel();
 
 Q_SIGNALS:
+    /*!
+        The associated index changed.
+     */
     void indexChanged(Index* index);
+    /*!
+        The query changed.
+     */
     void queryChanged(QVariant query);
+    /*!
+        The documents matching the query changed.
+     */
     void documentsChanged(QStringList documents);
+    /*!
+        The results matching the query changed.
+     */
     void resultsChanged(QList<QVariant> results);
 private:
     Q_DISABLE_COPY(Query)

=== modified file 'src/synchronizer.cpp'
--- src/synchronizer.cpp	2013-11-25 13:22:07 +0000
+++ src/synchronizer.cpp	2015-03-24 19:42:30 +0000
@@ -17,7 +17,6 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-#include <QDebug>
 #include <QSqlQuery>
 #include <QFile>
 #include <QSqlError>
@@ -33,10 +32,34 @@
 /*!
     \class Synchronizer
     \inmodule U1Db
+    \ingroup cpp
+
+    \brief The Synchronizer class handles synchronizing between two databases.
+ */
+
+/*!
+    \qmltype Synchronizer
+    \instantiates Synchronizer
+    \inqmlmodule U1db 1.0
     \ingroup modules
 
-    \brief The Synchronizer class handles synchronizing between two databases.
-
+    \brief Synchronizer handles synchronizing between two databases.
+
+    \qml
+        Synchronizer {
+            id: mySync
+            synchronize: false
+            source: myDatabase
+            targets: [ {
+                remote: true,
+                ip: "127.0.0.1",
+                port: 7777,
+                name: "example1.u1db",
+                resolve_to_source: true
+            } ]
+
+        }
+    \endqml
 */
 
 /*
@@ -50,20 +73,6 @@
 
     Synchronizer elements sync two databases together, a 'source' database and a remote or local 'target' database.
 
-    Example use in a QML application:
-
-    U1db.Synchronizer{
-        id: aSynchronizer
-        synchronize: false
-        source: aDatabase
-        targets: [{remote:true,
-        ip:"127.0.0.1",
-        port: 7777,
-        name:"example1.u1db",
-        resolve_to_source:true}]
-
-    }
-
     Short description of properties:
 
     id: The element's identification.
@@ -152,12 +161,8 @@
     return roles;
 }
 
-
 /*!
-
-
-    Sets the source database.
-
+    Sets the \a source database.
  */
 void Synchronizer::setSource(Database* source)
 {
@@ -173,15 +178,16 @@
     Q_EMIT sourceChanged(source);
 }
 
-
 /*!
- * \property Synchronizer::targets
+ * \qmlproperty Variant Synchronizer::targets
+ * \preliminary
  *
  * Sets meta-data for databases to be used during a synchronization session.
  *
  * The QVariant is a list that can contain definitions for more than one database
  * to be used as a target. For example:
  *
+ * \code
  * targets: [{remote:true},
  *  {remote:true,
  *  ip:"127.0.0.1",
@@ -189,6 +195,7 @@
  *  name:"example1.u1db",
  *  resolve_to_source:true},
  *  {remote:"OK"}]
+ * \endcode
  *
  * The above example defines three databases. Two of the three definitions in the
  * example are invalid, the first ({remote:true}) and the third ({remote:"OK"}),
@@ -197,11 +204,13 @@
  * The second definition is a fully defined and valid definition for a local to
  * remote synchronization of two databases:
  *
+ * \code
  * {remote:true,
  *  ip:"127.0.0.1",
  *  port: 7777,
  *  name:"example1.u1db",
  *  resolve_to_source:true}
+ * \endcode
  *
  * 'remote' determines whether the database is on disk or located on a server.
  * 'ip' and 'port' for a server are used only when 'remote' is set to true
@@ -209,9 +218,10 @@
  *  Note: If 'remote' is false this is the relative/absolute file location.
  * 'resolve_to_source' determines whether to resolve conflicts automatically
  * in favor of the source (aka local) database's values or the target's.
- *
- */
-
+ */
+/*!
+ * FIXME \a targets
+ */
 void Synchronizer::setTargets(QVariant targets)
 {
 
@@ -226,9 +236,12 @@
 }
 
 /*!
- * \property Synchronizer::synchronize
- */
-
+ * \qmlproperty bool Synchronizer::synchronize
+ * FIXME
+ */
+/*!
+ * FIXME \a synchronize
+ */
 void Synchronizer::setSync(bool synchronize)
 {
 
@@ -241,9 +254,15 @@
 
 
 /*!
- * \property Synchronizer::resolve_to_source
- */
-
+ * \qmlproperty bool Synchronizer::resolve_to_source
+ *
+ * If true, conflicts during sync will be resolved in favor of the content
+ * from the source database.
+ */
+/*!
+ * If \a resolve_to_source is true, conflicts during sync will be resolved in favor
+ * of the content from the source database.
+ */
 void Synchronizer::setResolveToSource(bool resolve_to_source)
 {
      if (m_resolve_to_source == resolve_to_source)
@@ -255,8 +274,6 @@
 
 
 /*!
- * \fn void Synchronizer::setSyncOutput(QList<QVariant> sync_output)
- *
  * Sets the current value for the active session's \a sync_output.
  *
  */
@@ -271,11 +288,12 @@
 }
 
 /*!
- * \property Synchronizer::source
- *
- *
- *  Returns a source Database.
- *
+ * \qmlproperty Database Synchronizer::source
+ *
+ *  Returns the source \l Database.
+ */
+/*!
+    Returns the source \l Database.
  */
 Database* Synchronizer::getSource()
 {
@@ -283,54 +301,36 @@
 }
 
 /*!
- * \brief Synchronizer::getTargets
- *
- *
  *  Returns meta-data for all target databases.
- *
  */
-
 QVariant Synchronizer::getTargets()
 {
      return m_targets;
 }
 
 /*!
- * \brief Synchronizer::getSync
- *
- *
  * Returns the current value of synchronize. If true then the synchronize
  * session is initiated.
  *
  * This should probaby always be set to false on application start up.
  * The application developer should use some trigger to switch it to true
  * when needed (e.g. button click).
- *
  */
-
 bool Synchronizer::getSync()
 {
      return m_synchronize;
 }
 
 /*!
- * \brief Synchronizer::getResolveToSource
- *
- *
- * If set to true, any document conflicts created during a sync session
- * will be resolved in favor of the content from the source database. If false
- * the content from the target database will replace the document content in
- * the source database.
- *
+ * Returns \b true if conflicts during sync will be resolved in favor of the content
+ * from the source database.
  */
-
 bool Synchronizer::getResolveToSource(){
     return m_resolve_to_source;
 }
 
 /*!
- * \property Synchronizer::sync_output
- * \brief Synchronizer::getSyncOutput
+ * \qmlproperty list<Variant> Synchronizer::sync_output
  *
  * Returns the output from a sync session. The list should contain numerous
  * QVariantMaps, each of which will have various meta-data with informative
@@ -343,19 +343,18 @@
  * The information can be used in any number of ways, such as on screen within an app,
  * testing, console output, logs and more. This is designed to be flexible enough that
  * the app developer can decide themselves how to best use the data.
- *
- */
-
+ */
+/*!
+ * FIXME
+ */
 QList<QVariant> Synchronizer::getSyncOutput(){
     return m_sync_output;
 }
 
 /*
-
  Below this line represents the class' more unique functionality.
  In other words, methods that do more than simply modify/retrieve
  an element's property values.
-
 */
 
 
@@ -363,7 +362,6 @@
  * \brief Synchronizer::onSyncChanged
  *
  * The synchroization process begins here.
- *
  */
 
 void Synchronizer::onSyncChanged(bool synchronize){
@@ -446,12 +444,10 @@
  * \internal
  * \brief Synchronizer::getValidTargets
  *
- *
  * This method confirms that each sync target definition is valid, based
  * on predefined criteria contained in the validator and mandatory lists.
  *
  */
-
 QList<QVariant> Synchronizer::getValidTargets(QMap<QString,QString>validator, QList<QString>mandatory){
 
     QList<QVariant> sync_targets;
@@ -1018,7 +1014,7 @@
                 return dbUid;
             }
             else{
-                qDebug() << query.lastError().text();
+                qWarning("u1db: %s", qPrintable(query.lastError().text()));
                 db.close();
                 return dbUid;
             }

=== modified file 'src/synchronizer.h'
--- src/synchronizer.h	2013-11-22 15:21:37 +0000
+++ src/synchronizer.h	2015-03-24 19:42:30 +0000
@@ -21,11 +21,8 @@
 #define U1DB_SYNCHRONIZER_H
 
 #include <QtCore/QObject>
-#include <QSqlDatabase>
 #include <QVariant>
-#include <QMetaType>
 #include <QtNetwork>
-#include <QNetworkAccessManager>
 
 
 #include "database.h"
@@ -37,13 +34,18 @@
 class Q_DECL_EXPORT Synchronizer : public QAbstractListModel {
     Q_OBJECT
 #ifdef Q_QDOC
+    /*! source */
     Q_PROPERTY(Database* source READ getSource WRITE setSource NOTIFY sourceChanged)   
 #else
     Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Database*) source READ getSource WRITE setSource NOTIFY sourceChanged)  
 #endif
+    /*! synchronize */
     Q_PROPERTY(bool synchronize READ getSync WRITE setSync NOTIFY syncChanged)
+    /*! resolve_to_source */
     Q_PROPERTY(bool resolve_to_source READ getResolveToSource WRITE setResolveToSource NOTIFY resolveToSourceChanged)
+    /*! targets */
     Q_PROPERTY(QVariant targets READ getTargets WRITE setTargets NOTIFY targetsChanged)
+    /*! sync_output */
     Q_PROPERTY(QList<QVariant> sync_output READ getSyncOutput NOTIFY syncOutputChanged)
 
 public: