Skip to content
This repository was archived by the owner on Mar 4, 2023. It is now read-only.

Commit bb61809

Browse files
Skycoder42Skycoder42
committed
updated general new doc stuff
1 parent ba8a364 commit bb61809

25 files changed

+254
-33
lines changed

‎deploy.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"title": "QtDataSync",
33
"description": "A simple offline-first synchronisation framework, to synchronize data of Qt applications between devices.",
4-
"modules": [ "QtDataSync" ],
4+
"modules": [ "QtDataSync", "QtDataSyncAndroid", "QtDataSyncIos" ],
55
"dependencies": [
66
".qtremoteobjects",
77
".skycoder42.jsonserializer",

‎doc/Doxyfile

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2128,7 +2128,8 @@ INCLUDE_FILE_PATTERNS = *.h \
21282128
# recursively expanded use the := operator instead of the = operator.
21292129
# This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
21302130

2131-
PREDEFINED = __cplusplus=201402L
2131+
PREDEFINED = __cplusplus=201402L \
2132+
= DOXYGEN_RUN
21322133

21332134
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
21342135
# tag can be used to specify a list of macro names that should be expanded. The

‎doc/accountmanager.dox

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,23 @@ events to deliver messages within the same process only. See
9999
@sa @ref ro_threaded "Threaded remote objects", Setup::remoteObjectHost
100100
*/
101101

102+
/*!
103+
@property QtDataSync::AccountManager::setupName
104+
105+
@default{`QtDataSync::DefaultSetup`}
106+
107+
The setup name is the name that was passed to the Setup::create method to create the datasync
108+
instance this manager is refering to.
109+
110+
@accessors{
111+
@readAc{setupName()}
112+
@notifyAc{setupNameChanged()}
113+
@revisionAc{2}
114+
}
115+
116+
@sa QtDataSync::DefaultSetup, Setup::create
117+
*/
118+
102119
/*!
103120
@property QtDataSync::AccountManager::deviceName
104121

‎doc/conflictresolver.dox

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@ are treated, you can reimplement this class and pass it to the setup.
99
@sa Setup::conflictResolver, ConflictResolver::resolveConflict, GenericConflictResolver
1010
*/
1111

12+
/*!
13+
@fn QtDataSync::ConflictResolver::setupName
14+
15+
@returns The name of the setup
16+
17+
@sa QtDataSync::Setup
18+
*/
19+
1220
/*!
1321
@fn QtDataSync::ConflictResolver::name
1422

‎doc/datastore.dox

Lines changed: 49 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,12 @@ completed. This of course only applies to pointer classes, as gadgets are used a
3030
@throws SetupDoesNotExistException Thrown if the given setup was not created yet
3131
*/
3232

33+
/*!
34+
@fn QtDataSync::DataStore::setupName
35+
@returns The name of the setup
36+
@sa QtDataSync::Setup
37+
*/
38+
3339
/*!
3440
@fn QtDataSync::DataStore::count(int) const
3541

@@ -96,6 +102,41 @@ return and cosume very much memory. For most situations however, this is not the
96102
@sa DataStore::iterate, DataStore::search, DataStore::load, DataStore::keys
97103
*/
98104

105+
/*!
106+
@fn QtDataSync::DataStore::contains(int, const QString &) const
107+
108+
@param metaTypeId The QMetaType type id of the type
109+
@param key The key of the dataset to be checked for existance
110+
@returns true if the dataset exists, false if not
111+
@throws LocalStoreException In case of an internal error
112+
113+
@sa DataStore::keys, DataStore::load
114+
*/
115+
116+
/*!
117+
@fn QtDataSync::DataStore::contains(const QString &) const
118+
119+
@tparam T The type of the dataset to check for
120+
@param key The key of the dataset to be checked for existance
121+
@returns true if the dataset exists, false if not
122+
@throws LocalStoreException In case of an internal error
123+
124+
@sa DataStore::keys, DataStore::load
125+
*/
126+
127+
/*!
128+
@fn QtDataSync::DataStore::contains(int, const QVariant &) const
129+
@copydetails DataStore::contains(int, const QString &) const
130+
@note The given QVariant must be convertible to a QString
131+
*/
132+
133+
/*!
134+
@fn QtDataSync::DataStore::contains(const K &) const
135+
@tparam K The type of the key to be returned as list
136+
@copydetails DataStore::contains(const QString &) const
137+
@note The given type K must be convertible to a QString
138+
*/
139+
99140
/*!
100141
@fn QtDataSync::DataStore::load(int, const QString &) const
101142

@@ -264,10 +305,17 @@ Semantics of the `iterator`:
264305
*/
265306

266307
/*!
267-
@fn QtDataSync::DataStore::iterate(const std::function<bool(T)> &) const
308+
@fn QtDataSync::DataStore::iterate(int, const std::function<bool(QVariant)> &, bool) const
309+
@param skipBroken Skip datasets that fail to load instead of thrown the exception
310+
@copydetails QtDataSync::DataStore::iterate(int, const std::function<bool(QVariant)> &) const
311+
*/
312+
313+
/*!
314+
@fn QtDataSync::DataStore::iterate(const std::function<bool(T)> &, bool) const
268315

269316
@tparam T The type to be iterated over
270317
@param iterator An iterator function that is called for every dataset of the given type
318+
@param skipBroken Skip datasets that fail to load instead of thrown the exception
271319
@throws LocalStoreException In case of an internal error
272320

273321
Semantics of the `iterator`:

‎doc/datatypestore.dox

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,16 @@ return and cosume very much memory. For most situations however, this is not the
114114
@sa DataTypeStore::iterate, DataTypeStore::search, DataTypeStore::load, DataTypeStore::keys
115115
*/
116116

117+
/*!
118+
@fn QtDataSync::DataTypeStore::contains
119+
120+
@param key The key of the dataset to be checked for existance
121+
@returns true if the dataset exists, false if not
122+
@throws LocalStoreException In case of an internal error
123+
124+
@sa DataTypeStore::keys, DataTypeStore::load
125+
*/
126+
117127
/*!
118128
@fn QtDataSync::DataTypeStore::load
119129

@@ -179,6 +189,7 @@ change signals for updated properties will be emitted.
179189
@fn QtDataSync::DataTypeStore::iterate
180190

181191
@param iterator An iterator function that is called for every dataset of the given type
192+
@param skipBroken Skip datasets that fail to load instead of thrown the exception
182193
@throws LocalStoreException In case of an internal error
183194

184195
Semantics of the `iterator`:

‎doc/keystore.dox

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,14 @@ methods
2323
@sa KeyStorePlugin
2424
*/
2525

26+
/*!
27+
@fn QtDataSync::KeyStore::setupName
28+
29+
@returns The name of the setup
30+
31+
@sa QtDataSync::Setup
32+
*/
33+
2634
/*!
2735
@fn QtDataSync::KeyStore::providerName
2836

‎doc/setup.dox

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,46 @@ AES applies for both, Setup::AES_EAX and Setup::AES_GCM:
385385
@sa Defaults::property, Defaults::SymKeyParam, Setup::cipherScheme
386386
*/
387387

388+
/*!
389+
@property QtDataSync::Setup::eventLoggingMode
390+
391+
@default{`EventMode::Unchanged`}
392+
393+
@note Event though the default value is EventMode::Unchanged, this implicitly means for newly
394+
created setups event logging is disabled! If you create a completly new setup and want event
395+
logging, you have to set this property to EventMode::Enabled at least once.
396+
397+
Event logging is an optional component of datasync that can be used for reliable, deterministic
398+
and ordered handling of change events from any source. The main class to access these events
399+
is the EventCursor. This property is used to control the activation of this component.
400+
401+
If disabled, no events are logged at all. This means EventCursor becomes unusable. If enabled,
402+
all changes to data (create, change and delete) trigger an event that is permanently stored and
403+
can be accessed vua the EventCursor. The Unchanged mode simply means "keep it in whatever state
404+
it already is" - this is useful if you don't want to break anything
405+
406+
@attention Setting this to EventMode::Disabled will immediatly drop **all** already stored change
407+
events! So unless you are certain you don't need these, be careful with that option.
408+
409+
@accessors{
410+
@readAc{eventLoggingMode()}
411+
@writeAc{setEventLoggingMode()}
412+
@resetAc{resetEventLoggingMode()}
413+
@revisionAc{2}
414+
}
415+
416+
@sa Defaults::property, Defaults::EventLoggingMode, QtDataSync::EventCursor, Setup::EventMode
417+
*/
418+
419+
/*!
420+
@fn QtDataSync::Setup::exists
421+
422+
@param name The name of the setup to check for
423+
@returns true if a setup already exists for that name, false if not
424+
425+
@sa Setup::create, SetupExistsException
426+
*/
427+
388428
/*!
389429
@fn QtDataSync::Setup::setCleanupTimeout
390430

‎doc/syncmanager.dox

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,23 @@ events to deliver messages within the same process only. See
1111
@sa @ref ro_threaded "Threaded remote objects", Setup::remoteObjectHost
1212
*/
1313

14+
/*!
15+
@property QtDataSync::SyncManager::setupName
16+
17+
@default{`QtDataSync::DefaultSetup`}
18+
19+
The setup name is the name that was passed to the Setup::create method to create the datasync
20+
instance this manager is refering to.
21+
22+
@accessors{
23+
@readAc{setupName()}
24+
@notifyAc{setupNameChanged()}
25+
@revisionAc{2}
26+
}
27+
28+
@sa QtDataSync::DefaultSetup, Setup::create
29+
*/
30+
1431
/*!
1532
@property QtDataSync::SyncManager::syncEnabled
1633

‎doc/userexchangemanager.dox

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,23 @@ they both are connected to supports broadcasts. It does <b>not</b> work across n
7272
@sa AccountManager
7373
*/
7474

75+
/*!
76+
@property QtDataSync::UserExchangeManager::setupName
77+
78+
@default{`QtDataSync::DefaultSetup`}
79+
80+
The setup name is the name that was passed to the Setup::create method to create the datasync
81+
instance this manager is refering to.
82+
83+
@accessors{
84+
@readAc{setupName()}
85+
@notifyAc{setupNameChanged()}
86+
@revisionAc{2}
87+
}
88+
89+
@sa QtDataSync::DefaultSetup, Setup::create
90+
*/
91+
7592
/*!
7693
@property QtDataSync::UserExchangeManager::active
7794

‎src/datasync/accountmanager.h

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ class Q_DATASYNC_EXPORT AccountManager : public QObject
120120
{
121121
Q_OBJECT
122122

123+
//! Holds the name of the setup this manager operates on
123124
Q_PROPERTY(QString setupName READ setupName NOTIFY setupNameChanged REVISION 2)
124125
//! The display name of the device
125126
Q_PROPERTY(QString deviceName READ deviceName WRITE setDeviceName RESET resetDeviceName NOTIFY deviceNameChanged)
@@ -162,6 +163,7 @@ class Q_DATASYNC_EXPORT AccountManager : public QObject
162163
//! @copydoc importAccountTrusted(const QJsonObject &, const QString &, const std::function<void(bool,QString)> &, bool)
163164
void importAccountTrusted(const QByteArray &importData, const QString &password, const std::function<void(bool,QString)> &completedFn, bool keepData = false);
164165

166+
//! @readAcFn{AccountManager::setupName}
165167
QString setupName() const;
166168
//! @readAcFn{AccountManager::deviceName}
167169
QString deviceName() const;
@@ -202,7 +204,8 @@ public Q_SLOTS:
202204
//! Is emitted when a device has been granted access to the current account
203205
void accountAccessGranted(const QUuid &deviceId, QPrivateSignal);
204206

205-
Q_REVISION(2) void setupNameChanged(const QString &setupName, QPrivateSignal);
207+
//! @notifyAcFn{AccountManager::setupName}
208+
QT_DATASYNC_REVISION_2 void setupNameChanged(const QString &setupName, QPrivateSignal);
206209
//! @notifyAcFn{AccountManager::deviceName}
207210
void deviceNameChanged(const QString &deviceName, QPrivateSignal);
208211
//! @notifyAcFn{AccountManager::deviceFingerprint}

‎src/datasync/conflictresolver.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ class Q_DATASYNC_EXPORT ConflictResolver : public QObject
2626
//! @private
2727
void setDefaults(const Defaults &defaults);
2828

29+
//! Returns the name of the setup this class operates on
2930
QString setupName() const;
3031
//! The resolvers name. Used for logging
3132
virtual QByteArray name() const;

‎src/datasync/datastore.h

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,7 @@ class Q_DATASYNC_EXPORT DataStore : public QObject
4141
explicit DataStore(const QString &setupName, QObject *parent = nullptr);
4242
~DataStore() override;
4343

44+
//! Returns the name of the setup this class operates on
4445
QString setupName() const;
4546

4647
//! @copybrief DataStore::count() const
@@ -49,7 +50,9 @@ class Q_DATASYNC_EXPORT DataStore : public QObject
4950
QStringList keys(int metaTypeId) const;
5051
//! @copybrief DataStore::loadAll() const
5152
QVariantList loadAll(int metaTypeId) const;
53+
//! @copybrief DataStore::contains(const QString &) const
5254
bool contains(int metaTypeId, const QString &key) const;
55+
//! @copybrief DataStore::contains(const QString &) const
5356
inline bool contains(int metaTypeId, const QVariant &key) const {
5457
return contains(metaTypeId, key.toString());
5558
}
@@ -71,9 +74,10 @@ class Q_DATASYNC_EXPORT DataStore : public QObject
7174
void update(int metaTypeId, QObject *object) const;
7275
//! @copybrief DataStore::search(const QString &, SearchMode) const
7376
QVariantList search(int metaTypeId, const QString &query, SearchMode mode = RegexpMode) const;
74-
//! @copybrief DataStore::iterate(const std::function<bool(T)> &) const
77+
//! @copybrief DataStore::iterate(const std::function<bool(T)> &, bool) const
7578
void iterate(int metaTypeId,
7679
const std::function<bool(QVariant)> &iterator) const;
80+
//! @copybrief DataStore::iterate(const std::function<bool(T)> &, bool) const
7781
void iterate(int metaTypeId,
7882
const std::function<bool(QVariant)> &iterator,
7983
bool skipBroken) const; //MAJOR merge overloads
@@ -96,11 +100,13 @@ class Q_DATASYNC_EXPORT DataStore : public QObject
96100
//! Loads all existing datasets for the given type
97101
template<typename T>
98102
QList<T> loadAll() const;
99-
//! Loads the dataset with the given key for the given type
103+
//! Checks if a dataset exists in the store for the given key
100104
template<typename T>
101105
bool contains(const QString &key) const;
106+
//! @copybrief DataStore::contains(const QString &) const
102107
template<typename T, typename K>
103108
bool contains(const K &key) const;
109+
//! Loads the dataset with the given key for the given type
104110
template<typename T>
105111
T load(const QString &key) const;
106112
//! @copybrief DataStore::load(const QString &) const

‎src/datasync/datastoremodel.h

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ class Q_DATASYNC_EXPORT DataStoreModel : public QAbstractTableModel
3131

3232
//! Returns the data store the model works on
3333
DataStore *store() const;
34+
//! @copydoc DataStore::setupName
3435
QString setupName() const;
3536

3637
//! @readAcFn{DataStoreModel::typeId}

‎src/datasync/datatypestore.h

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ class Q_DATASYNC_EXPORT DataTypeStoreBase : public QObject
2222

2323
//! Returns a reference to the internally used DataStore
2424
virtual DataStore *store() const = 0;
25+
//! @copydoc DataStore::setupName
2526
QString setupName() const;
2627

2728
Q_SIGNALS:
@@ -53,6 +54,7 @@ class DataTypeStore : public DataTypeStoreBase
5354
QList<TKey> keys() const;
5455
//! @copybrief DataStore::loadAll() const
5556
QList<TType> loadAll() const;
57+
//! @copybrief DataStore::contains(const K &) const
5658
bool contains(const TKey &key) const;
5759
//! @copybrief DataStore::load(const K &) const
5860
TType load(const TKey &key) const;
@@ -65,7 +67,7 @@ class DataTypeStore : public DataTypeStoreBase
6567
void update(std::enable_if_t<__helpertypes::is_object<TX>::value, TX> object) const;
6668
//! @copybrief DataStore::search(const QString &, SearchMode) const
6769
QList<TType> search(const QString &query, DataStore::SearchMode mode = DataStore::RegexpMode);
68-
//! @copybrief DataStore::iterate(const std::function<bool(T)> &) const
70+
//! @copybrief DataStore::iterate(const std::function<bool(T)> &, bool) const
6971
void iterate(const std::function<bool(TType)> &iterator, bool skipBroken = false);
7072
//! @copybrief DataStore::clear()
7173
void clear();
@@ -104,7 +106,7 @@ class CachingDataTypeStore : public DataTypeStoreBase
104106
qint64 count() const;
105107
//! @copybrief DataTypeStore::keys
106108
QList<TKey> keys() const;
107-
//! Checks if a dataset for the given key exists
109+
//! @copybrief DataTypeStore::contains
108110
bool contains(const TKey &key) const;
109111
//! @copybrief DataTypeStore::loadAll
110112
QList<TType> loadAll() const;

0 commit comments

Comments
 (0)