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

Proposed by Cris Dywan
Status: Merged
Approved by: Cris Dywan
Approved revision: 118
Merged at revision: 124
Proposed branch: lp:~kalikiana/u1db-qt/qmlDocs
Merge into: lp:u1db-qt
Diff against target: 1204 lines (+367/-149)
11 files modified
documentation/u1db.qdocconf (+1/-6)
src/database.cpp (+66/-15)
src/database.h (+10/-0)
src/document.cpp (+68/-21)
src/document.h (+20/-1)
src/index.cpp (+49/-18)
src/index.h (+12/-1)
src/query.cpp (+54/-14)
src/query.h (+16/-0)
src/synchronizer.cpp (+66/-70)
src/synchronizer.h (+5/-3)
To merge this branch: bzr merge lp:~kalikiana/u1db-qt/qmlDocs
Reviewer Review Type Date Requested Status
PS Jenkins bot continuous-integration Approve
Marco Trevisan (Treviño) Approve
Review via email: mp+208818@code.launchpad.net

Commit message

Port qdoc syntax to QML annotations

Description of the change

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.

To post a comment you must log in.
Revision history for this message
PS Jenkins bot (ps-jenkins) wrote :
review: Needs Fixing (continuous-integration)
Revision history for this message
PS Jenkins bot (ps-jenkins) wrote :
review: Approve (continuous-integration)
Revision history for this message
Marco Trevisan (Treviño) (3v1n0) wrote :

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

review: Approve
lp:~kalikiana/u1db-qt/qmlDocs updated
118. By Cris Dywan

Clarify path behavior documentation

Revision history for this message
PS Jenkins bot (ps-jenkins) wrote :
review: Approve (continuous-integration)

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'documentation/u1db.qdocconf'
2--- documentation/u1db.qdocconf 2013-09-06 10:00:36 +0000
3+++ documentation/u1db.qdocconf 2015-03-24 19:42:30 +0000
4@@ -5,12 +5,7 @@
5
6 sourcedirs = ../src \
7 ../documentation
8-headers = ../src/database.h \
9- ../src/document.h \
10- ../src/index.h \
11- ../src/query.h \
12- ../src/synchronizer.h \
13- ../src/global.h
14+headerdirs = ../src/
15 Cpp.ignoretokens = Q_DECL_EXPORT \
16 Q_PROPERTY \
17 QT_BEGIN_NAMESPACE_U1DB \
18
19=== modified file 'src/database.cpp'
20--- src/database.cpp 2015-02-19 10:37:54 +0000
21+++ src/database.cpp 2015-03-24 19:42:30 +0000
22@@ -17,7 +17,6 @@
23 * along with this program. If not, see <http://www.gnu.org/licenses/>.
24 */
25
26-#include <QDebug>
27 #include <QSqlQuery>
28 #include <QFile>
29 #include <QFileInfo>
30@@ -63,16 +62,41 @@
31 /*!
32 \class Database
33 \inmodule U1Db
34- \ingroup modules
35+ \ingroup cpp
36
37- \brief The Database class implements the on-disk storage of an individual
38- U1DB database.
39+ \brief The Database class implements on-disk storage for documents and indexes.
40
41 Database can be used as a QAbstractListModel, delegates will then have access to \a docId and \a contents
42 analogous to the properties of Document.
43 */
44
45 /*!
46+ \qmltype Database
47+ \instantiates Database
48+ \inqmlmodule U1Db 1.0
49+ \ingroup modules
50+
51+ \brief Database implements on-disk storage for documents and indexes.
52+
53+ In a ListView the Database can be used as a model which includes all documents
54+ in the database. For listing only a subset of documents Query can be used.
55+
56+ \qml
57+ ListView {
58+ model: Database {
59+ id: myDatabase
60+ }
61+ delegate: ListItem.Subtitled {
62+ text: docId
63+ subText: contents.color
64+ }
65+ }
66+ \endqml
67+
68+ \sa Query
69+*/
70+
71+/*!
72 A unique identifier for the state of synchronization
73 */
74 QString
75@@ -110,7 +134,10 @@
76 }
77
78 /*!
79- \property Database::error
80+ \qmlproperty string Database::error
81+ The last error as a string if the last operation failed.
82+ */
83+/*!
84 The last error as a string if the last operation failed.
85 */
86 QString
87@@ -335,10 +362,16 @@
88
89
90 /*!
91+ \qmlmethod Variant Database::getDoc(string)
92 Returns the contents of a document by \a docId in a form that QML recognizes
93 as a Variant object, it's identical to Document::getContents() with the
94 same \a docId.
95 */
96+/*!
97+ * Returns the contents of a document by \a docId in a form that QML recognizes
98+ * as a Variant object, it's identical to Document::getContents() with the
99+ * same \a docId.
100+ */
101 QVariant
102 Database::getDoc(const QString& docId)
103 {
104@@ -513,7 +546,6 @@
105
106 /*!
107 * \internal
108- * \brief Database::updateDocRevisionNumber
109 *
110 * Whenever a document as added or modified it needs a new revision number.
111 *
112@@ -614,6 +646,14 @@
113 }
114
115 /*!
116+ \qmlmethod string Database::putDoc(var, string)
117+ Updates the existing \a contents of the document identified by \a docId if
118+ there's no error.
119+ If no \a docId is given or \a docId is an empty string the \a contents will be
120+ stored under an autogenerated name.
121+ Returns the new revision of the document, or -1 on failure.
122+ */
123+/*!
124 Updates the existing \a contents of the document identified by \a docId if
125 there's no error.
126 If no \a docId is given or \a docId is an empty string the \a contents will be
127@@ -687,6 +727,10 @@
128 }
129
130 /*!
131+ \qmlmethod void Database::deleteDoc(string)
132+ Deletes the document identified by \a docId.
133+ */
134+/*!
135 Deletes the document identified by \a docId.
136 */
137 void
138@@ -710,6 +754,10 @@
139
140
141 /*!
142+ \qmlmethod list<string> Database::listDocs()
143+ Returns a list of all stored documents by their docId.
144+ */
145+/*!
146 Returns a list of all stored documents by their docId.
147 */
148 QList<QString>
149@@ -737,11 +785,17 @@
150 }
151
152 /*!
153- \property Database::path
154- A relative filename can be given to store the database in an app-specific
155- writable folder. This is recommended as it ensures to work with confinement.
156- If more control is needed absolute paths can be used.
157- By default everything is stored in memory.
158+ \qmlproperty string Database::path
159+ A relative \a path can be given to store the database in an app-specific
160+ writable folder. This is recommended as it ensures to work with confinement.
161+ If more control is needed absolute paths or local file URIs can be used.
162+ By default or if the path is empty everything is stored in memory.
163+ */
164+/*!
165+ A relative \a path can be given to store the database in an app-specific
166+ writable folder. This is recommended as it ensures to work with confinement.
167+ If more control is needed absolute paths or local file URIs can be used.
168+ By default or if the path is empty everything is stored in memory.
169 */
170 void
171 Database::setPath(const QString& path)
172@@ -759,10 +813,7 @@
173 }
174
175 /*!
176- * \brief Database::getPath
177- *
178- * Simply returns the path of the database.
179- *
180+ * Returns the path of the database.
181 */
182 QString
183 Database::getPath()
184
185=== modified file 'src/database.h'
186--- src/database.h 2014-01-24 11:13:35 +0000
187+++ src/database.h 2015-03-24 19:42:30 +0000
188@@ -31,7 +31,9 @@
189
190 class Q_DECL_EXPORT Database : public QAbstractListModel {
191 Q_OBJECT
192+ /*! path */
193 Q_PROPERTY(QString path READ getPath WRITE setPath NOTIFY pathChanged)
194+ /*! error */
195 Q_PROPERTY(QString error READ lastError NOTIFY errorChanged)
196 public:
197 Database(QObject* parent = 0);
198@@ -65,7 +67,15 @@
199 QMap<QString,QVariant> getSyncLogInfo(QMap<QString,QVariant> lastSyncInformation, QString uid, QString prefix);
200
201 Q_SIGNALS:
202+ /*!
203+ \signal Database::pathChanged
204+ The database path changed - the empty string means it's in-memory only.
205+ */
206 void pathChanged(const QString& path);
207+ /*!
208+ \signal Database::errorChanged
209+ An error occurred. Use lastError() to check it.
210+ */
211 void errorChanged(const QString& error);
212 /*!
213 A document's contents were modified.
214
215=== modified file 'src/document.cpp'
216--- src/document.cpp 2015-02-19 10:37:54 +0000
217+++ src/document.cpp 2015-03-24 19:42:30 +0000
218@@ -17,14 +17,6 @@
219 * along with this program. If not, see <http://www.gnu.org/licenses/>.
220 */
221
222-#include <QDebug>
223-#include <QSqlQuery>
224-#include <QFile>
225-#include <QSqlError>
226-#include <QUuid>
227-#include <QStringList>
228-#include <QJsonDocument>
229-
230 #include "document.h"
231 #include "private.h"
232
233@@ -33,12 +25,34 @@
234 /*!
235 \class Document
236 \inmodule U1db
237+ \ingroup cpp
238+
239+ \brief The Document class proxies a single document stored in the Database.
240+*/
241+
242+
243+/*!
244+ \qmltype Document
245+ \instantiates Document
246+ \inqmlmodule U1db 1.0
247 \ingroup modules
248
249- \brief The Document class proxies a single document stored in the Database.
250+ \brief Document proxies a single document stored in the Database.
251
252 This is the declarative API equivalent of Database::putDoc() and
253 Database::getDoc().
254+
255+ \qml
256+ Document {
257+ docId: 'myId'
258+ defaults: {
259+ color: 'blue'
260+ }
261+ create: true
262+ }
263+ \endqml
264+
265+ \sa Database
266 */
267
268 /*!
269@@ -50,6 +64,9 @@
270 {
271 }
272
273+/*!
274+ Returns the \l Database.
275+ */
276 Database*
277 Document::getDatabase()
278 {
279@@ -77,8 +94,7 @@
280 }
281
282 /*!
283- \property Document::database
284- The database is used to lookup the contents of the document, reflecting
285+ The \a database is used to lookup the contents of the document, reflecting
286 changes done to it and conversely changes are saved to the database.
287 */
288 void
289@@ -104,6 +120,9 @@
290 Q_EMIT databaseChanged(database);
291 }
292
293+/*!
294+ Returns the docId.
295+ */
296 QString
297 Document::getDocId()
298 {
299@@ -111,11 +130,16 @@
300 }
301
302 /*!
303- \property Document::docId
304+ \qmlproperty string Document::docId
305 The docId can be that of an existing document in the database and
306 will determine what getContents() returns.
307 If no such documents exists, setDefaults() can be used to supply a preset.
308 */
309+/*!
310+ The \a docId can be that of an existing document in the database and
311+ will determine what getContents() returns.
312+ If no such documents exists, setDefaults() can be used to supply a preset.
313+ */
314 void
315 Document::setDocId(const QString& docId)
316 {
317@@ -132,6 +156,9 @@
318 }
319 }
320
321+/*!
322+ Returns whether the document will be newly created if it doesn't exist.
323+ */
324 bool
325 Document::getCreate()
326 {
327@@ -139,8 +166,12 @@
328 }
329
330 /*!
331- \property Document::create
332- If create is true, docId is not empty and no document with the same docId
333+ \qmlproperty bool Document::create
334+ If \a create is true, docId is not empty and no document with the same docId
335+ exists, defaults will be used to store the document.
336+ */
337+/*!
338+ If \a create is true, docId is not empty and no document with the same docId
339 exists, defaults will be used to store the document.
340 */
341 void
342@@ -156,6 +187,10 @@
343 m_database->putDoc(m_defaults, m_docId);
344 }
345
346+/*!
347+ Returns the defaults to be used when the document is newly created
348+ because it doesn't exist, if create is true.
349+ */
350 QVariant
351 Document::getDefaults()
352 {
353@@ -163,11 +198,17 @@
354 }
355
356 /*!
357- \property Document::defaults
358- The default contents of the document, which are used only if
359- create is true, docId is not empty and no document with the same
360- docId exists in the database yet.
361- If the defaults change, it's up to the API user to handle it.
362+ \qmlproperty Variant Document::content
363+ The default contents of the document, which are used only if
364+ create is true, docId is not empty and no document with the same
365+ docId exists in the database yet.
366+ If the \a defaults change, it's up to the API user to handle it.
367+ */
368+/*!
369+ The default contents of the document, which are used only if
370+ create is true, docId is not empty and no document with the same
371+ docId exists in the database yet.
372+ If the \a defaults change, it's up to the API user to handle it.
373 */
374 void
375 Document::setDefaults(QVariant defaults)
376@@ -185,6 +226,9 @@
377 m_database->putDoc(m_defaults, m_docId);
378 }
379
380+/*!
381+ Returns the current contents of the document.
382+ */
383 QVariant
384 Document::getContents()
385 {
386@@ -192,8 +236,11 @@
387 }
388
389 /*!
390- \property Document::contents
391- Updates the contents of the document. A valid docId must be set.
392+ \qmlproperty Variant Document::contents
393+ Updates the \a contents of the document. A valid docId must be set.
394+ */
395+/*!
396+ Updates the \a contents of the document. A valid docId must be set.
397 */
398 void
399 Document::setContents(QVariant contents)
400
401=== modified file 'src/document.h'
402--- src/document.h 2013-04-23 15:17:24 +0000
403+++ src/document.h 2015-03-24 19:42:30 +0000
404@@ -21,7 +21,6 @@
405 #define U1DB_DOCUMENT_H
406
407 #include <QtCore/QObject>
408-#include <QSqlDatabase>
409 #include <QVariant>
410
411 #include "database.h"
412@@ -31,13 +30,18 @@
413 class Q_DECL_EXPORT Document : public QObject {
414 Q_OBJECT
415 #ifdef Q_QDOC
416+ /*! database */
417 Q_PROPERTY(Database* database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
418 #else
419 Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Database*) database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
420 #endif
421+ /*! docId */
422 Q_PROPERTY(QString docId READ getDocId WRITE setDocId NOTIFY docIdChanged)
423+ /*! create */
424 Q_PROPERTY(bool create READ getCreate WRITE setCreate NOTIFY createChanged)
425+ /*! defaults */
426 Q_PROPERTY(QVariant defaults READ getDefaults WRITE setDefaults NOTIFY defaultsChanged)
427+ /*! contents */
428 Q_PROPERTY(QVariant contents READ getContents WRITE setContents NOTIFY contentsChanged)
429 public:
430 Document(QObject* parent = 0);
431@@ -53,10 +57,25 @@
432 QVariant getContents();
433 void setContents(QVariant contents);
434 Q_SIGNALS:
435+ /*!
436+ The database changed.
437+ */
438 void databaseChanged(Database* database);
439+ /*!
440+ The docId changed.
441+ */
442 void docIdChanged(const QString& docId);
443+ /*!
444+ The create flag changed.
445+ */
446 void createChanged(bool create);
447+ /*!
448+ The default contents changed.
449+ */
450 void defaultsChanged(QVariant defaults);
451+ /*!
452+ The current contents of the document changed.
453+ */
454 void contentsChanged(QVariant contents);
455 private:
456 Q_DISABLE_COPY(Document)
457
458=== modified file 'src/index.cpp'
459--- src/index.cpp 2014-01-31 19:20:07 +0000
460+++ src/index.cpp 2015-03-24 19:42:30 +0000
461@@ -17,13 +17,7 @@
462 * along with this program. If not, see <http://www.gnu.org/licenses/>.
463 */
464
465-#include <QDebug>
466-#include <QSqlQuery>
467-#include <QFile>
468-#include <QSqlError>
469-#include <QUuid>
470 #include <QStringList>
471-#include <QJsonDocument>
472
473 #include "index.h"
474 #include "private.h"
475@@ -32,15 +26,33 @@
476
477 /*!
478 \class Index
479- \inmodule U1Db
480- \ingroup modules
481+ \inmodule U1db
482+ \ingroup cpp
483
484 \brief The Index class defines an index to be stored in the database and
485 queried using Query. Changes in documents affected by the index also update
486 the index in the database.
487-
488- This is the declarative API equivalent of Database::putIndex() and
489- Database::getIndexExpressions().
490+*/
491+
492+/*!
493+ \qmltype Index
494+ \instantiates Index
495+ \inqmlmodule U1db 1.0
496+ \ingroup modules
497+
498+ \brief An Index defines what fields can be filtered using Query.
499+
500+ Documents in the database will be included if they contain all fields in the expression.
501+
502+ \qml
503+ Index {
504+ database: myDatabase
505+ name: 'colorIndex'
506+ expression: [ 'color' ]
507+ }
508+ \endqml
509+
510+ \sa Query
511 */
512
513 /*!
514@@ -52,6 +64,9 @@
515 {
516 }
517
518+/*!
519+ Returns the \l Database to lookup documents from and store the index in.
520+ */
521 Database*
522 Index::getDatabase()
523 {
524@@ -71,11 +86,16 @@
525 }
526
527 /*!
528- \property Index::database
529+ \qmlproperty Database Index::database
530 Sets the Database to lookup documents from and store the index in. The
531 dataInvalidated() signal will be emitted on all changes that could affect
532 the index.
533 */
534+/*!
535+ Sets the \a database to lookup documents from and store the index in. The
536+ dataInvalidated() signal will be emitted on all changes that could affect
537+ the index.
538+ */
539 void
540 Index::setDatabase(Database* database)
541 {
542@@ -98,6 +118,9 @@
543
544 }
545
546+/*!
547+ Returns the name of the index. Both name and expression must be specified.
548+ */
549 QString
550 Index::getName()
551 {
552@@ -105,10 +128,14 @@
553 }
554
555 /*!
556- \property Index::name
557+ \qmlproperty string Index::name
558 Sets the name used. Both an expression and a name must be specified
559 for an index to be created.
560 */
561+/*!
562+ Sets the \a name used. Both an expression and a name must be specified
563+ for an index to be created.
564+ */
565 void
566 Index::setName(const QString& name)
567 {
568@@ -125,6 +152,9 @@
569 Q_EMIT nameChanged(name);
570 }
571
572+/*!
573+ Returns the expression of the index. Both name and expression must be specified.
574+ */
575 QStringList
576 Index::getExpression()
577 {
578@@ -132,12 +162,17 @@
579 }
580
581 /*!
582- \property Index::expression
583+ \qmlproperty list<string> Index::expression
584 Sets the expression used. Both an expression and a name must be specified
585 for an index to be created.
586
587 Also starts the process of creating the Index result list, which can then be queried or populate the Query model as is.
588+ */
589+/*!
590+ Sets the \a expression used. Both an expression and a name must be specified
591+ for an index to be created.
592
593+ Also starts the process of creating the Index result list, which can then be queried or populate the Query model as is.
594 */
595 void
596 Index::setExpression(QStringList expression)
597@@ -189,7 +224,6 @@
598 /*!
599 \internal
600 */
601-
602 QList<QVariantMap> Index::getAllResults(){
603 generateIndexResults();
604 return m_results;
605@@ -205,7 +239,6 @@
606 */
607 QStringList Index::appendResultsFromMap(QString docId, QStringList fieldsList, QVariantMap current_section, QString current_field)
608 {
609-
610 QMapIterator<QString, QVariant> i(current_section);
611
612 QString original_field = current_field;
613@@ -259,8 +292,6 @@
614 *This recursive method is used in conjuntion with Index::appendResultsFromMap, to aid in iterating through a document when an embedded list is found.
615 *
616 */
617-
618-
619 QStringList Index::getFieldsFromList(QString docId, QStringList fieldsList, QVariantList current_section, QString current_field)
620 {
621
622
623=== modified file 'src/index.h'
624--- src/index.h 2013-04-25 13:38:33 +0000
625+++ src/index.h 2015-03-24 19:42:30 +0000
626@@ -21,7 +21,6 @@
627 #define U1DB_INDEX_H
628
629 #include <QtCore/QObject>
630-#include <QSqlDatabase>
631 #include <QStringList>
632
633 #include "database.h"
634@@ -31,11 +30,14 @@
635 class Q_DECL_EXPORT Index : public QObject {
636 Q_OBJECT
637 #ifdef Q_QDOC
638+ /*! database */
639 Q_PROPERTY(Database* database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
640 #else
641 Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Database*) database READ getDatabase WRITE setDatabase NOTIFY databaseChanged)
642 #endif
643+ /*! name */
644 Q_PROPERTY(QString name READ getName WRITE setName NOTIFY nameChanged)
645+ /*! expression */
646 Q_PROPERTY(QStringList expression READ getExpression WRITE setExpression NOTIFY expressionChanged)
647 public:
648 Index(QObject* parent = 0);
649@@ -49,8 +51,17 @@
650 QList<QVariantMap> getAllResults();
651
652 Q_SIGNALS:
653+ /*!
654+ The database changed.
655+ */
656 void databaseChanged(Database* database);
657+ /*!
658+ The index name changed.
659+ */
660 void nameChanged(const QString& name);
661+ /*!
662+ The index expression changed.
663+ */
664 void expressionChanged(QVariant expression);
665 /*!
666 The database, an indexed document or the expressions changed.
667
668=== modified file 'src/query.cpp'
669--- src/query.cpp 2014-03-13 19:31:58 +0000
670+++ src/query.cpp 2015-03-24 19:42:30 +0000
671@@ -17,13 +17,7 @@
672 * along with this program. If not, see <http://www.gnu.org/licenses/>.
673 */
674
675-#include <QDebug>
676-#include <QSqlQuery>
677-#include <QFile>
678-#include <QSqlError>
679-#include <QUuid>
680 #include <QStringList>
681-#include <QJsonDocument>
682
683 #include "query.h"
684 #include "database.h"
685@@ -34,12 +28,42 @@
686 /*!
687 \class Query
688 \inmodule U1db
689- \ingroup modules
690+ \ingroup cpp
691
692 \brief The Query class generates a filtered list of documents based on a query using the given Index.
693
694 Query can be used as a QAbstractListModel, delegates will then have access to \a docId and \a contents
695 analogous to the properties of Document.
696+ */
697+
698+/*!
699+ \qmltype Query
700+ \instantiates Query
701+ \inqmlmodule U1db 1.0
702+ \ingroup modules
703+
704+ \brief Query filters documents based on the query and index.
705+
706+ In a ListView the Query can be used as a model.
707+
708+ \qml
709+ ListView {
710+ model: Query {
711+ index: Index {
712+ name: 'colorIndex'
713+ expression: [ 'color' ]
714+ database: myDatabase
715+ }
716+ query: [ 'blue' ]
717+ }
718+ delegate: ListItem.Subtitled {
719+ text: docId
720+ subText: contents.color
721+ }
722+ }
723+ \endqml
724+
725+ \sa Index
726 */
727
728 /*!
729@@ -93,6 +117,9 @@
730 return m_results.count();
731 }
732
733+/*!
734+ FIXME
735+ */
736 Index*
737 Query::getIndex()
738 {
739@@ -287,10 +314,13 @@
740 }
741
742 /*!
743- \property Query::index
744- Sets the Index to use. The index must have a valid name and index expressions.
745+ \qmlproperty Index Query::index
746+ Sets the Index to use. \a index must have a valid name and index expressions.
747 If no query is set, the default is all results of the index.
748 */
749+/*!
750+ FIXME \a index
751+ */
752 void
753 Query::setIndex(Index* index)
754 {
755@@ -305,11 +335,12 @@
756 }
757 Q_EMIT indexChanged(index);
758
759-
760 onDataInvalidated();
761-
762 }
763
764+/*!
765+ FIXME
766+ */
767 QVariant
768 Query::getQuery()
769 {
770@@ -317,11 +348,14 @@
771 }
772
773 /*!
774- \property Query::query
775+ \qmlproperty Variant Query::query
776 A query in one of the allowed forms:
777 'value', ['value'] or [{'sub-field': 'value'}].
778 The default is equivalent to '*'.
779 */
780+/*!
781+ FIXME \a query
782+ */
783 void
784 Query::setQuery(QVariant query)
785 {
786@@ -334,9 +368,12 @@
787 }
788
789 /*!
790- \property Query::documents
791+ \qmlproperty list<string> Query::documents
792 The docId's of all matched documents.
793 */
794+/*!
795+ FIXME
796+ */
797 QStringList
798 Query::getDocuments()
799 {
800@@ -344,9 +381,12 @@
801 }
802
803 /*!
804- \property Query::results
805+ \qmlproperty list<Variant> Query::results
806 The results of the query as a list.
807 */
808+/*!
809+ FIXME
810+ */
811 QList<QVariant>
812 Query::getResults()
813 {
814
815=== modified file 'src/query.h'
816--- src/query.h 2014-03-07 17:54:07 +0000
817+++ src/query.h 2015-03-24 19:42:30 +0000
818@@ -30,12 +30,16 @@
819 class Q_DECL_EXPORT Query : public QAbstractListModel {
820 Q_OBJECT
821 #ifdef Q_QDOC
822+ /*! index */
823 Q_PROPERTY(Index* index READ getIndex WRITE setIndex NOTIFY indexChanged)
824 #else
825 Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Index*) index READ getIndex WRITE setIndex NOTIFY indexChanged)
826 #endif
827+ /*! query */
828 Q_PROPERTY(QVariant query READ getQuery WRITE setQuery NOTIFY queryChanged)
829+ /*! documents */
830 Q_PROPERTY(QStringList documents READ getDocuments NOTIFY documentsChanged)
831+ /*! results */
832 Q_PROPERTY(QList<QVariant> results READ getResults NOTIFY resultsChanged)
833 public:
834 Query(QObject* parent = 0);
835@@ -55,9 +59,21 @@
836 void resetModel();
837
838 Q_SIGNALS:
839+ /*!
840+ The associated index changed.
841+ */
842 void indexChanged(Index* index);
843+ /*!
844+ The query changed.
845+ */
846 void queryChanged(QVariant query);
847+ /*!
848+ The documents matching the query changed.
849+ */
850 void documentsChanged(QStringList documents);
851+ /*!
852+ The results matching the query changed.
853+ */
854 void resultsChanged(QList<QVariant> results);
855 private:
856 Q_DISABLE_COPY(Query)
857
858=== modified file 'src/synchronizer.cpp'
859--- src/synchronizer.cpp 2013-11-25 13:22:07 +0000
860+++ src/synchronizer.cpp 2015-03-24 19:42:30 +0000
861@@ -17,7 +17,6 @@
862 * along with this program. If not, see <http://www.gnu.org/licenses/>.
863 */
864
865-#include <QDebug>
866 #include <QSqlQuery>
867 #include <QFile>
868 #include <QSqlError>
869@@ -33,10 +32,34 @@
870 /*!
871 \class Synchronizer
872 \inmodule U1Db
873+ \ingroup cpp
874+
875+ \brief The Synchronizer class handles synchronizing between two databases.
876+ */
877+
878+/*!
879+ \qmltype Synchronizer
880+ \instantiates Synchronizer
881+ \inqmlmodule U1db 1.0
882 \ingroup modules
883
884- \brief The Synchronizer class handles synchronizing between two databases.
885-
886+ \brief Synchronizer handles synchronizing between two databases.
887+
888+ \qml
889+ Synchronizer {
890+ id: mySync
891+ synchronize: false
892+ source: myDatabase
893+ targets: [ {
894+ remote: true,
895+ ip: "127.0.0.1",
896+ port: 7777,
897+ name: "example1.u1db",
898+ resolve_to_source: true
899+ } ]
900+
901+ }
902+ \endqml
903 */
904
905 /*
906@@ -50,20 +73,6 @@
907
908 Synchronizer elements sync two databases together, a 'source' database and a remote or local 'target' database.
909
910- Example use in a QML application:
911-
912- U1db.Synchronizer{
913- id: aSynchronizer
914- synchronize: false
915- source: aDatabase
916- targets: [{remote:true,
917- ip:"127.0.0.1",
918- port: 7777,
919- name:"example1.u1db",
920- resolve_to_source:true}]
921-
922- }
923-
924 Short description of properties:
925
926 id: The element's identification.
927@@ -152,12 +161,8 @@
928 return roles;
929 }
930
931-
932 /*!
933-
934-
935- Sets the source database.
936-
937+ Sets the \a source database.
938 */
939 void Synchronizer::setSource(Database* source)
940 {
941@@ -173,15 +178,16 @@
942 Q_EMIT sourceChanged(source);
943 }
944
945-
946 /*!
947- * \property Synchronizer::targets
948+ * \qmlproperty Variant Synchronizer::targets
949+ * \preliminary
950 *
951 * Sets meta-data for databases to be used during a synchronization session.
952 *
953 * The QVariant is a list that can contain definitions for more than one database
954 * to be used as a target. For example:
955 *
956+ * \code
957 * targets: [{remote:true},
958 * {remote:true,
959 * ip:"127.0.0.1",
960@@ -189,6 +195,7 @@
961 * name:"example1.u1db",
962 * resolve_to_source:true},
963 * {remote:"OK"}]
964+ * \endcode
965 *
966 * The above example defines three databases. Two of the three definitions in the
967 * example are invalid, the first ({remote:true}) and the third ({remote:"OK"}),
968@@ -197,11 +204,13 @@
969 * The second definition is a fully defined and valid definition for a local to
970 * remote synchronization of two databases:
971 *
972+ * \code
973 * {remote:true,
974 * ip:"127.0.0.1",
975 * port: 7777,
976 * name:"example1.u1db",
977 * resolve_to_source:true}
978+ * \endcode
979 *
980 * 'remote' determines whether the database is on disk or located on a server.
981 * 'ip' and 'port' for a server are used only when 'remote' is set to true
982@@ -209,9 +218,10 @@
983 * Note: If 'remote' is false this is the relative/absolute file location.
984 * 'resolve_to_source' determines whether to resolve conflicts automatically
985 * in favor of the source (aka local) database's values or the target's.
986- *
987- */
988-
989+ */
990+/*!
991+ * FIXME \a targets
992+ */
993 void Synchronizer::setTargets(QVariant targets)
994 {
995
996@@ -226,9 +236,12 @@
997 }
998
999 /*!
1000- * \property Synchronizer::synchronize
1001- */
1002-
1003+ * \qmlproperty bool Synchronizer::synchronize
1004+ * FIXME
1005+ */
1006+/*!
1007+ * FIXME \a synchronize
1008+ */
1009 void Synchronizer::setSync(bool synchronize)
1010 {
1011
1012@@ -241,9 +254,15 @@
1013
1014
1015 /*!
1016- * \property Synchronizer::resolve_to_source
1017- */
1018-
1019+ * \qmlproperty bool Synchronizer::resolve_to_source
1020+ *
1021+ * If true, conflicts during sync will be resolved in favor of the content
1022+ * from the source database.
1023+ */
1024+/*!
1025+ * If \a resolve_to_source is true, conflicts during sync will be resolved in favor
1026+ * of the content from the source database.
1027+ */
1028 void Synchronizer::setResolveToSource(bool resolve_to_source)
1029 {
1030 if (m_resolve_to_source == resolve_to_source)
1031@@ -255,8 +274,6 @@
1032
1033
1034 /*!
1035- * \fn void Synchronizer::setSyncOutput(QList<QVariant> sync_output)
1036- *
1037 * Sets the current value for the active session's \a sync_output.
1038 *
1039 */
1040@@ -271,11 +288,12 @@
1041 }
1042
1043 /*!
1044- * \property Synchronizer::source
1045- *
1046- *
1047- * Returns a source Database.
1048- *
1049+ * \qmlproperty Database Synchronizer::source
1050+ *
1051+ * Returns the source \l Database.
1052+ */
1053+/*!
1054+ Returns the source \l Database.
1055 */
1056 Database* Synchronizer::getSource()
1057 {
1058@@ -283,54 +301,36 @@
1059 }
1060
1061 /*!
1062- * \brief Synchronizer::getTargets
1063- *
1064- *
1065 * Returns meta-data for all target databases.
1066- *
1067 */
1068-
1069 QVariant Synchronizer::getTargets()
1070 {
1071 return m_targets;
1072 }
1073
1074 /*!
1075- * \brief Synchronizer::getSync
1076- *
1077- *
1078 * Returns the current value of synchronize. If true then the synchronize
1079 * session is initiated.
1080 *
1081 * This should probaby always be set to false on application start up.
1082 * The application developer should use some trigger to switch it to true
1083 * when needed (e.g. button click).
1084- *
1085 */
1086-
1087 bool Synchronizer::getSync()
1088 {
1089 return m_synchronize;
1090 }
1091
1092 /*!
1093- * \brief Synchronizer::getResolveToSource
1094- *
1095- *
1096- * If set to true, any document conflicts created during a sync session
1097- * will be resolved in favor of the content from the source database. If false
1098- * the content from the target database will replace the document content in
1099- * the source database.
1100- *
1101+ * Returns \b true if conflicts during sync will be resolved in favor of the content
1102+ * from the source database.
1103 */
1104-
1105 bool Synchronizer::getResolveToSource(){
1106 return m_resolve_to_source;
1107 }
1108
1109 /*!
1110- * \property Synchronizer::sync_output
1111- * \brief Synchronizer::getSyncOutput
1112+ * \qmlproperty list<Variant> Synchronizer::sync_output
1113 *
1114 * Returns the output from a sync session. The list should contain numerous
1115 * QVariantMaps, each of which will have various meta-data with informative
1116@@ -343,19 +343,18 @@
1117 * The information can be used in any number of ways, such as on screen within an app,
1118 * testing, console output, logs and more. This is designed to be flexible enough that
1119 * the app developer can decide themselves how to best use the data.
1120- *
1121- */
1122-
1123+ */
1124+/*!
1125+ * FIXME
1126+ */
1127 QList<QVariant> Synchronizer::getSyncOutput(){
1128 return m_sync_output;
1129 }
1130
1131 /*
1132-
1133 Below this line represents the class' more unique functionality.
1134 In other words, methods that do more than simply modify/retrieve
1135 an element's property values.
1136-
1137 */
1138
1139
1140@@ -363,7 +362,6 @@
1141 * \brief Synchronizer::onSyncChanged
1142 *
1143 * The synchroization process begins here.
1144- *
1145 */
1146
1147 void Synchronizer::onSyncChanged(bool synchronize){
1148@@ -446,12 +444,10 @@
1149 * \internal
1150 * \brief Synchronizer::getValidTargets
1151 *
1152- *
1153 * This method confirms that each sync target definition is valid, based
1154 * on predefined criteria contained in the validator and mandatory lists.
1155 *
1156 */
1157-
1158 QList<QVariant> Synchronizer::getValidTargets(QMap<QString,QString>validator, QList<QString>mandatory){
1159
1160 QList<QVariant> sync_targets;
1161@@ -1018,7 +1014,7 @@
1162 return dbUid;
1163 }
1164 else{
1165- qDebug() << query.lastError().text();
1166+ qWarning("u1db: %s", qPrintable(query.lastError().text()));
1167 db.close();
1168 return dbUid;
1169 }
1170
1171=== modified file 'src/synchronizer.h'
1172--- src/synchronizer.h 2013-11-22 15:21:37 +0000
1173+++ src/synchronizer.h 2015-03-24 19:42:30 +0000
1174@@ -21,11 +21,8 @@
1175 #define U1DB_SYNCHRONIZER_H
1176
1177 #include <QtCore/QObject>
1178-#include <QSqlDatabase>
1179 #include <QVariant>
1180-#include <QMetaType>
1181 #include <QtNetwork>
1182-#include <QNetworkAccessManager>
1183
1184
1185 #include "database.h"
1186@@ -37,13 +34,18 @@
1187 class Q_DECL_EXPORT Synchronizer : public QAbstractListModel {
1188 Q_OBJECT
1189 #ifdef Q_QDOC
1190+ /*! source */
1191 Q_PROPERTY(Database* source READ getSource WRITE setSource NOTIFY sourceChanged)
1192 #else
1193 Q_PROPERTY(QT_PREPEND_NAMESPACE_U1DB(Database*) source READ getSource WRITE setSource NOTIFY sourceChanged)
1194 #endif
1195+ /*! synchronize */
1196 Q_PROPERTY(bool synchronize READ getSync WRITE setSync NOTIFY syncChanged)
1197+ /*! resolve_to_source */
1198 Q_PROPERTY(bool resolve_to_source READ getResolveToSource WRITE setResolveToSource NOTIFY resolveToSourceChanged)
1199+ /*! targets */
1200 Q_PROPERTY(QVariant targets READ getTargets WRITE setTargets NOTIFY targetsChanged)
1201+ /*! sync_output */
1202 Q_PROPERTY(QList<QVariant> sync_output READ getSyncOutput NOTIFY syncOutputChanged)
1203
1204 public:

Subscribers

People subscribed via source and target branches

to all changes: