← Back to team overview

uonedb-qt team mailing list archive

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

 

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

Commit message:
Port qdoc syntax to QML annotations

Requested reviews:
  U1DB Qt developers (uonedb-qt)
Related bugs:
  Bug #1277601 in U1DB Qt/ QML: "Need QML documentation"
  https://bugs.launchpad.net/u1db-qt/+bug/1277601

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

This gets us QML docs, including a few tweaks to ensure each has one example at the top. Behind each component a link is available to reveal the c++ version.
Unfortunately qdoc now refuses to use the explanations with C++ and warns a lot. I know no way around that I'm inclinded to bite the bullet to get decent QML docs now, as I don't have a lot of time for it.
-- 
https://code.launchpad.net/~kalikiana/u1db-qt/qmlDocs/+merge/208818
Your team U1DB Qt developers is requested to review the proposed merge of lp:~kalikiana/u1db-qt/qmlDocs into lp:u1db-qt.
=== modified file 'documentation/u1db.qdocconf'
--- documentation/u1db.qdocconf	2013-09-06 10:00:36 +0000
+++ documentation/u1db.qdocconf	2014-02-28 14:38:31 +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	2014-02-17 16:52:42 +0000
+++ src/database.cpp	2014-02-28 14:38:31 +0000
@@ -37,16 +37,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
@@ -84,7 +109,7 @@
 }
 
 /*!
-    \property Database::error
+    \qmlproperty string Database::error
     The last error as a string if the last operation failed.
  */
 QString
@@ -302,6 +327,7 @@
 
 
 /*!
+    \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.
@@ -480,7 +506,6 @@
 
 /*!
  * \internal
- * \brief Database::updateDocRevisionNumber
  *
  * Whenever a document as added or modified it needs a new revision number.
  *
@@ -581,6 +606,7 @@
 }
 
 /*!
+    \qmlmethod string Database::putDoc(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
@@ -649,6 +675,7 @@
 }
 
 /*!
+    \qmlmethod void Database::deleteDoc(string)
     Deletes the document identified by \a docId.
  */
 void
@@ -672,6 +699,7 @@
 
 
 /*!
+    \qmlmethod list<string> Database::listDocs()
     Returns a list of all stored documents by their docId.
  */
 QList<QString>
@@ -699,7 +727,7 @@
 }
 
 /*!
-    \property Database::path
+    \qmlproperty string 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.

=== modified file 'src/document.cpp'
--- src/document.cpp	2013-04-23 15:17:24 +0000
+++ src/document.cpp	2014-02-28 14:38:31 +0000
@@ -33,12 +33,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
 */
 
 /*!
@@ -77,7 +99,7 @@
 }
 
 /*!
-    \property Document::database
+    \qmlproperty Database Document::database
     The database is used to lookup the contents of the document, reflecting
     changes done to it and conversely changes are saved to the database.
  */
@@ -111,7 +133,7 @@
 }
 
 /*!
-    \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.
@@ -139,7 +161,7 @@
 }
 
 /*!
-    \property Document::create
+    \qmlproperty bool Document::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.
  */
@@ -163,7 +185,7 @@
 }
 
 /*!
-    \property Document::defaults
+    \qmlproperty Variant 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.
@@ -189,7 +211,7 @@
 }
 
 /*!
-    \property Document::contents
+    \qmlproperty Variant Document::contents
     Updates the contents of the document. A valid docId must be set.
  */
 void

=== modified file 'src/index.cpp'
--- src/index.cpp	2014-01-31 19:20:07 +0000
+++ src/index.cpp	2014-02-28 14:38:31 +0000
@@ -32,15 +32,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
 */
 
 /*!
@@ -71,7 +89,7 @@
 }
 
 /*!
-    \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.
@@ -105,7 +123,7 @@
 }
 
 /*!
-    \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.
  */
@@ -132,7 +150,7 @@
 }
 
 /*!
-    \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.
 

=== modified file 'src/query.cpp'
--- src/query.cpp	2014-01-31 19:20:07 +0000
+++ src/query.cpp	2014-02-28 14:38:31 +0000
@@ -34,12 +34,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
 */
 
 /*!
@@ -335,7 +365,7 @@
 }
 
 /*!
-    \property Query::index
+    \qmlproperty Index Query::index
     Sets the Index to use. The index must have a valid name and index expressions.
     If no query is set, the default is all results of the index.
  */
@@ -365,7 +395,7 @@
 }
 
 /*!
-    \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 '*'.
@@ -382,7 +412,7 @@
 }
 
 /*!
-    \property Query::documents
+    \qmlproperty list<string> Query::documents
     The docId's of all matched documents.
  */
 QStringList
@@ -392,7 +422,7 @@
 }
 
 /*!
-    \property Query::results
+    \qmlproperty list<Variant> Query::results
     The results of the query as a list.
  */
 QList<QVariant>

=== modified file 'src/synchronizer.cpp'
--- src/synchronizer.cpp	2013-11-25 13:22:07 +0000
+++ src/synchronizer.cpp	2014-02-28 14:38:31 +0000
@@ -33,10 +33,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 +74,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.
@@ -175,7 +185,8 @@
 
 
 /*!
- * \property Synchronizer::targets
+ * \qmlproperty Variant Synchronizer::targets
+ * \preliminary
  *
  * Sets meta-data for databases to be used during a synchronization session.
  *
@@ -226,7 +237,7 @@
 }
 
 /*!
- * \property Synchronizer::synchronize
+ * \qmlproperty bool Synchronizer::synchronize
  */
 
 void Synchronizer::setSync(bool synchronize)
@@ -241,7 +252,7 @@
 
 
 /*!
- * \property Synchronizer::resolve_to_source
+ * \qmlproperty bool Synchronizer::resolve_to_source
  */
 
 void Synchronizer::setResolveToSource(bool resolve_to_source)
@@ -255,8 +266,6 @@
 
 
 /*!
- * \fn void Synchronizer::setSyncOutput(QList<QVariant> sync_output)
- *
  * Sets the current value for the active session's \a sync_output.
  *
  */
@@ -271,7 +280,7 @@
 }
 
 /*!
- * \property Synchronizer::source
+ * \qmlproperty Database Synchronizer::source
  *
  *
  *  Returns a source Database.
@@ -329,7 +338,7 @@
 }
 
 /*!
- * \property Synchronizer::sync_output
+ * \qmlproperty list<Variant> Synchronizer::sync_output
  * \brief Synchronizer::getSyncOutput
  *
  * Returns the output from a sync session. The list should contain numerous


Follow ups