updated doc

Author: Skycoder42

doc/asyncdatastore.dox

@@ -28,6 +28,26 @@ objects after the operations have been completed.
 @sa CachingDataStore
 */
 
+/*!
+@fn QtDataSync::AsyncDataStore::iterate(const std::function<bool(T)> &, const std::function<void(const QException &)> &)
+
+@param iterator The iterator to be called for each dataset loaded
+@param onExcept A handler to be called if reading fails at some point
+
+Inernally, the store will load one dataset after another, and call iterator with the result.
+You can return `true` to continue iterating, or `false` to cancel prematurely. The exception
+handler is passed to to the Tasks internally used.
+
+@sa Task
+*/
+
+/*!
+@fn QtDataSync::AsyncDataStore::iterate(int, const std::function<bool(QVariant)> &, const std::function<void(const QException &)> &)
+
+@param metaTypeId The type of datasets to iterate over
+@copydetails AsyncDataStore::iterate(const std::function<bool(T)> &, const std::function<void(const QException &)> &)
+*/
+
 /*!
 @fn QtDataSync::AsyncDataStore::dataChanged
 

doc/authenticator.dox

@@ -15,7 +15,7 @@ RemoteConnector::createAuthenticator
 
 @param extraData Additional data that is passed to the remote connector, e.g. a password
 @param resetLocalStore Specifies, whether the local store should be reset or not
-@returns A task to wait on for the completition of the reset.
+@returns A task to wait on for the completition of the reset
 
 If you need to perform an operation that will change the currently logged in user, reset his
 device identity or somthing similiar, that changes his "identity", use this method. Use the
@@ -29,3 +29,37 @@ use this approach.
 
 @sa RemoteConnector::resetUserId, RemoteConnector::resetUserData
 */
+
+/*!
+@fn QtDataSync::Authenticator::exportUserDataImpl
+
+@param device The device to write the exported data to
+
+This method should export all of a users "identity" data. This includes all the keys, ids and
+more that are needed to properly synchronize and identify. it's internally called by
+exportUserData().
+
+It must be possible to login the user on a different device by exporting data with this method
+and importing it with importUserData(). No additional information should be required. (The only
+exption beeing a "password". It's up to your implemetation If you want to export passwords too,
+or require the user to provide it)
+
+@sa Authenticator::exportUserData, Authenticator::importUserDataImpl
+*/
+
+/*!
+@fn QtDataSync::Authenticator::importUserDataImpl
+
+@param device The device to read the data to import from
+@returns A task to wait on for the completition of the import
+
+This method should import all of a users "identity" data from the given device, that was
+previously exported by exportUserData(). it's internally called by importUserData().
+
+It must be possible to login the user on a different device by exporting data  and importing it
+on the device with this methods. No additional information should be required. (The only
+exption beeing a "password". It's up to your implemetation If you want to export passwords too,
+or require the user to provide it)
+
+@sa Authenticator::importUserData, Authenticator::exportUserDataImpl
+*/

doc/encryptor.dox

@@ -0,0 +1,42 @@
+/*!
+@class QtDataSync::Encryptor
+
+It is used by the datasync engine to encrypt user data before it is sent to the server, and
+decrypt the data loaded from the server. It provides an abstract interface to perform encryption
+with whatever algorithm you want to use. The default implementation uses [QTinyAes](https://github.com/Skycoder42/QTinyAes),
+a Qt wrapper around [tiny-AES128-C](https://github.com/kokke/tiny-AES128-C).
+
+If you implement the methods, you must do it synchronously. Since the datasync instance
+engine, as well as this holder, run on their own thread, you won't block the ui.
+
+@attention The encryptor is constructed on the main thread, and then later moved to the datasync
+instance thread. The initialize() function is the first to be called after changing the thread.
+You should do nothing in the constructor, and all the initialization inside of that function,
+to ensure a fast and smooth usage.
+
+@sa Setup::setEncryptor, Setup::encryptor, RemoteConnector::cryptor
+*/
+
+/*!
+@fn QtDataSync::Encryptor::encrypt
+
+@param key The object key (type and key) of the object to be encrypted
+@param object The object to be encrypted
+@param keyProperty The property of the object that is the key property (the USER-property)
+@returns The encrypted data, wrapped inside a json value
+@throws QException If encryption failed
+
+@sa Encryptor::decrypt, RemoteConnector::upload
+*/
+
+/*!
+@fn QtDataSync::Encryptor::decrypt
+
+@param key The object key (type and key) of the object to be decrypted
+@param data The encrypted data, wrapped inside a json value
+@param keyProperty The property of the object that is the key property (the USER-property)
+@returns The decrypted json object
+@throws QException If decryption failed
+
+@sa Encryptor::encrypt, RemoteConnector::download
+*/

doc/remoteconnector.dox

@@ -85,12 +85,16 @@ the object. Since the object already contains the key (as the keyProperty proper
 can simply check the value of that property as the key. You do not have to use this property,
 but you can. One example would be a document store.
 
+@attention If cryptor() is valid, you should use the encryptor to decrypt the received data.
+Of course that is only if your implementation encrypts data as well.
+
 The result of this operation must be reported by calling operationDone(). The result
 parameter must be the downloaded json object, passed via the json value.
 
 If your operation fails, emit operationFailed() with an error message.
 
-@sa RemoteConnector::operationDone, RemoteConnector::operationFailed
+@sa RemoteConnector::operationDone, RemoteConnector::operationFailed,
+RemoteConnector::cryptor, Encryptor::encrypt
 */
 
 /*!
@@ -105,6 +109,9 @@ the object. Since the object already contains the key (as the keyProperty proper
 can simply save the object only, and use the key property for indexing etc. One example would
 be a document store.
 
+@attention If cryptor() is valid, you should use the encryptor to encrypt the `object` before
+sending it to the server
+
 The result of this operation must be reported by calling operationDone(). The result
 parameter is ignored, you can set it to QJsonValue::Undefined.
 
@@ -115,7 +122,7 @@ client. The server should implicitly do the same as for a markUnchanged() operat
 uploading.
 
 @sa RemoteConnector::operationDone, RemoteConnector::operationFailed,
-RemoteConnector::markUnchanged
+RemoteConnector::markUnchanged, RemoteConnector::cryptor, Encryptor::encrypt
 */
 
 /*!

doc/task.dox

@@ -39,3 +39,15 @@ the future has finished, the handlers will *not* be called anymore.
 @param parent The parent object to bind the handlers to
 @copydetails Task::onResult(const std::function<void(QVariant)> &, const std::function<void(const QException &)> &)
 */
+
+/*!
+@class QtDataSync::UpdateTask
+
+Instead of creating a new object for the loaded data, this class will be given an existing
+instance of the target object type. The result and onResult methods do not return a new object,
+instead they update the existing object to the result of the task. This way pointer classes
+can be easily updated, without having to exchange the references everywhere. The task is used
+by AsyncDataStore::loadInto.
+
+@sa AsyncDataStore::loadInto
+*/

src/datasync/authenticator.h

@@ -37,7 +37,9 @@ class Q_DATASYNC_EXPORT Authenticator : public QObject
 	//! Call this method to reset the users identity.
 	GenericTask<void> resetIdentity(const QVariant &extraData = {}, bool resetLocalStore = true);
 
+	//! Implements the user data export
 	virtual void exportUserDataImpl(QIODevice *device) const = 0;
+	//! Implements the user data import
 	virtual GenericTask<void> importUserDataImpl(QIODevice *device) = 0;
 
 	//! Returns a reference to the connector this authenticator belongs to

src/datasync/encryptor.h

@@ -8,6 +8,7 @@
 
 namespace QtDataSync {
 
+//! The class responsible for en/decrypting user data before exchaning it with the remote
 class Encryptor : public QObject
 {
 	Q_OBJECT
@@ -28,7 +29,7 @@ class Encryptor : public QObject
 
 	//! Encrypts the given dataset
 	virtual QJsonValue encrypt(const ObjectKey &key, const QJsonObject &object, const QByteArray &keyProperty) const = 0;
-	//! Encrypts the given dataset
+	//! Decrypts the given dataset
 	virtual QJsonObject decrypt(const ObjectKey &key, const QJsonValue &data, const QByteArray &keyProperty) const = 0;
 };
 

src/datasync/task.h

@@ -89,14 +89,15 @@ class Q_DATASYNC_EXPORT GenericTask<void> : public Task
 };
 
 template <typename T>
+//! Generic Task that updates an existing dataset instead of creating a new one (objects only)
 class UpdateTask : public Task
 {
 	static_assert(std::is_base_of<QObject, typename std::remove_pointer<T>::type>::value, "T must inherit QObject");
 
 	friend class AsyncDataStore;
 
 public:
-	//! Constructor with future interface
+	//! Constructor with future interface and the dataset to be updated
 	UpdateTask(T data, QFutureInterface<QVariant> d = {});
 
 	//! @copydoc Task::onResult(QObject *, const std::function<void(QVariant)> &, const std::function<void(const QException &)> &)