completed doc

Skycoder42 · Skycoder42 · commit 3b9afd27af16 · 2018-06-15T16:57:18.000+02:00
diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -1928,7 +1928,7 @@ RTF_SOURCE_CODE        = NO
 # classes and files.
 # The default value is: NO.
 
-GENERATE_MAN           = NO
+GENERATE_MAN           = YES
 
 # The MAN_OUTPUT tag is used to specify where the man pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
diff --git a/doc/datastoremodel.dox b/doc/datastoremodel.dox
@@ -49,18 +49,25 @@ auto model = new QtDataSync::DataStoreModel(this);
 model->setTypeId<Person>();
 @endcode
 
-To properly use it with widgets, you can use
-[QObjectListModel's](https://github.com/Skycoder42/QObjectListModel) `QObjectProxyModel`. The code
-below creates a model with 2 columns, where column 0 shows the "name" role and column 1 shows the
-"age" role:
+One additional feature of the model is, that it can also serve as model for table/tree views by
+delegating properties to multiple columns. This way you can use the model from QML by using the
+property names, and from widgets by delegating the properties to extra columns. For the above
+sample, the following code will result in a model with 2 columns, presenting the name and age
+properties as the Qt::DisplayRole of each column:
+
 @code{.cpp}
-auto proxy = new QObjectProxyModel({"name", "age"}, this);
-proxy->setSourceModel(model);
-proxy->addMapping(0, Qt::DisplayRole, "name");
-proxy->addMapping(1, Qt::DisplayRole, "age");
+// setup first
+auto model = new QtDataSync::DataStoreModel(this);
+model->setTypeId<Person>();
+
+// add the column config:
+auto col0 = model->addColumn("Name");
+model->addRole(col0, Qt::DisplayRole, "name");
+// or as shortcut for the above:
+model->addColumn("Age", "age");
 @endcode
 
-@sa DataStore, [QObjectListModel](https://github.com/Skycoder42/QObjectListModel)
+@sa DataStore
 */
 
 /*!
@@ -79,9 +86,11 @@ properly.
 @accessors{
 	@readAc{typeId()}
 	@writeAc{setTypeId()}
+	@notifyAc{typeIdChanged()}
 }
 
-@sa DataStoreModel::storeError, DataStoreModel::reload
+@sa DataStoreModel::storeError, DataStoreModel::reload, DataStoreModel::addColumn,
+DataStoreModel::addRole
 */
 
 /*!
@@ -165,3 +174,50 @@ DataStore::load.
 @sa DataStoreModel::object, DataStore::load
 */
 
+/*!
+@fn QVariant QtDataSync::DataStoreModel::addColumn(const QString &)
+
+@param text The display name of the column header
+@returns The index of the newly created column
+
+The method add a column to the model that can be used to present propeties from the underlying
+data as specific roles.
+
+@attention If no custom columns have been added yet, the model with have a single column with
+the typeId class name as title. By calling this method the first time, this default column will
+be **replaced** by whatever column you specify. All subsequent columns are simply added as new
+columns.
+
+@sa DataStoreModel, DataStoreModel::typeId, DataStore::addRole, DataStore::clearColumns
+*/
+
+/*!
+@fn QVariant QtDataSync::DataStoreModel::addColumn(const QString &, const char *)
+
+@param text The display name of the column header
+@param propertyName The name of the property to presented as the display role of that column
+@returns The index of the newly created column
+
+This method is basically a shortcut for:
+
+@code{.cpp}
+auto column = model->addColumn(text);
+model->addRole(column, Qt::DisplayRole, propertyName
+@endcode
+
+@sa DataStoreModel, DataStoreModel::typeId, DataStore::addRole, DataStore::clearColumns
+*/
+
+/*!
+@fn QVariant QtDataSync::DataStoreModel::addRole
+
+@param column The existing column to add the role to
+@param role The role that should be added to the column
+@param propertyName The name of the property to presented as the give role of that column
+
+This method adds a new role to an existing column. The new role will simply the the value of the
+given property of the object in each row. It's basically a delegate to the properties role.
+
+@sa DataStoreModel, DataStoreModel::typeId, DataStore::addColumn, DataStore::clearColumns
+*/
+
diff --git a/doc/setup.dox b/doc/setup.dox
@@ -461,6 +461,32 @@ This may take a moment to complete, depending on the keystore beeing used.
 @sa Setup::keystoreProviders, Setup::availableKeystores
 */
 
+/*!
+@fn QtDataSync::Setup::loadKeystore(QObject *, const QString &)
+
+@param parent The parent object to set as the keystores parent
+@param setupName The name of the setup to create the keystore for
+@returns A newly created KeyStore instance or nullptr if the keystore does not exist
+@throws SetupDoesNotExistException If the setup specified by setupName does not exist (yet)
+@throws QException If something went wrong while loading the plugin
+
+This method simply creates a keystore instance. This can be useful if you want to use a
+keystore outside of datasync to store your own secrets there.
+
+@note The keystore still requires a valid and running datasync instance, as it is needed
+for logging etc. This is only due to how the keystore is designed, as external access was
+originally not planned, and may change in the future.
+
+@sa KeyStore, Setup::keystoreProviders, Setup::defaultKeystoreProvider
+*/
+
+/*!
+@fn QtDataSync::Setup::loadKeystore(const QString &, QObject *, const QString &)
+
+@param provider The keystore provider to create a keystore for
+@copydetails Setup::loadKeystore(QObject *, const QString &)
+*/
+
 /*!
 @fn QtDataSync::Setup::defaultKeystoreProvider
 
@@ -480,6 +506,35 @@ the plain provider is returned, even if it is not available. The list is sorted
 @sa Setup::keystoreProviders, Setup::availableKeystores
 */
 
+/*!
+@fn QtDataSync::Setup::setAccount(const QJsonObject &, bool, bool)
+
+@param importData The account data to be imported
+@param keepData Specify whether the stored data should be preserved
+@param allowFailure Specify how a failure to import the account should be treated
+
+This method is basically a shortcut to import an account on creation - which is faster and
+much more efficient than first creating a new account and then delete it again to import an
+existing one. Internally, the same things will happen as with AccountManager::importAccount
+(or AccountManager::importAccountTrusted).
+
+Whats special is that since there is no account manager to handle a failure, there are two
+way to handle that. If `allowFailure` is false (the default), failing to import the data
+will trigger a fatal error. If it is set to true, the error is only printed and a new account
+is created instead, so that the engine can continue running.
+
+@sa Setup::setAccount, Setup::setAccountTrusted, AccountManager::importAccount,
+AccountManager::importAccountTrusted,
+*/
+
+/*!
+@fn QtDataSync::Setup::setAccountTrusted(const QJsonObject &, const QString &, bool, bool)
+
+@param password The password used to decrypt the imported data with. Must be the same as used
+for the export
+@copydetails Setup::setAccount(const QJsonObject &, bool, bool)
+*/
+
 /*!
 @fn QtDataSync::Setup::create
 
diff --git a/src/datasync/conflictresolver.h b/src/datasync/conflictresolver.h
@@ -70,6 +70,7 @@ class GenericConflictResolver : public GenericConflictResolver<Args...>
 	}
 
 protected:
+	//! @private
 	using NoConflictResultException = typename GenericConflictResolver<Args...>::NoConflictResultException;
 
 	/*!
@@ -79,12 +80,16 @@ class GenericConflictResolver : public GenericConflictResolver<Args...>
 	 * @param data2 The second dataset
 	 * @param parent A temporary qobject to use as parent for created QObjects
 	 * @returns The independent merge result of the two datasets
-	 * 	@throws QException In case data corruption was detected an exception can be thrown to abort the
+	 * @throws NoConflictResultException Thrown if resolving was not possible and the default JSON-based
+	 * resolving should be used instead
+	 * @throws QException In case data corruption was detected an exception can be thrown to abort the
 	 * synchronization. This will put the engine in an (unrecoverable) error state.
 	 *
 	 * Must be implemented as the main method of the resolver. The method *must* always return something.
-	 * Unlike the json variant, you cannot return a "default" result. No matter what is returned, it is
-	 * always used as it. Thus, you cannot return nullptr.
+	 * If you find that you cannot decide how to merge, simply throw the `NoConflictResultException`.
+	 * In that case, the library will ignore the result and proceed to merge as if no conflict resolver
+	 * was present. It's basically this methods equivalent of returning an empty JSON object on the
+	 * non generic variant of this method.
 	 *
 	 * @warning This method **must** be deterministic and independent of the parameter order. This means
 	 * if you assume you have 2 objects, no matter at what point in time and in which order they are
@@ -122,6 +127,7 @@ class GenericConflictResolver<T1> : public ConflictResolver
 	}
 
 protected:
+	//! An exception to be thrown from resolveConflict() if resolving was not possible and the default JSON-based resolving should be used instead
 	class NoConflictResultException {};
 
 	/*!
@@ -131,12 +137,16 @@ class GenericConflictResolver<T1> : public ConflictResolver
 	 * @param data2 The second dataset
 	 * @param parent A temporary qobject to use as parent for created QObjects
 	 * @returns The independent merge result of the two datasets
-	 * 	@throws QException In case data corruption was detected an exception can be thrown to abort the
+	 * @throws NoConflictResultException Thrown if resolving was not possible and the default JSON-based
+	 * resolving should be used instead
+	 * @throws QException In case data corruption was detected an exception can be thrown to abort the
 	 * synchronization. This will put the engine in an (unrecoverable) error state.
 	 *
 	 * Must be implemented as the main method of the resolver. The method *must* always return something.
-	 * Unlike the json variant, you cannot return a "default" result. No matter what is returned, it is
-	 * always used as it. Thus, you cannot return nullptr.
+	 * If you find that you cannot decide how to merge, simply throw the `NoConflictResultException`.
+	 * In that case, the library will ignore the result and proceed to merge as if no conflict resolver
+	 * was present. It's basically this methods equivalent of returning an empty JSON object on the
+	 * non generic variant of this method.
 	 *
 	 * @warning This method **must** be deterministic and independent of the parameter order. This means
 	 * if you assume you have 2 objects, no matter at what point in time and in which order they are
diff --git a/src/datasync/datastoremodel.cpp b/src/datasync/datastoremodel.cpp
@@ -240,6 +240,12 @@ void DataStoreModel::addRole(int column, int role, const char *propertyName)
 		emit dataChanged(this->index(0, column), this->index(rowCount() - 1, column), {role});
 }
 
+void DataStoreModel::clearColumns()
+{
+	d->columns.clear();
+	d->roleMapping.clear();
+}
+
 void DataStoreModel::setTypeId(int typeId)
 {
 	setTypeId(typeId, true);
@@ -256,10 +262,8 @@ void DataStoreModel::setTypeId(int typeId, bool resetColumns)
 		beginResetModel();
 		d->isObject = flags.testFlag(QMetaType::PointerToQObject);
 		d->keyList.clear();
-		if(resetColumns) {
-			d->columns.clear();
-			d->roleMapping.clear();
-		}
+		if(resetColumns)
+			clearColumns();
 		d->clearHashObjects();
 		d->createRoleNames();
 
diff --git a/src/datasync/datastoremodel.h b/src/datasync/datastoremodel.h
@@ -40,16 +40,18 @@ class Q_DATASYNC_EXPORT DataStoreModel : public QAbstractTableModel
 	//! @readAcFn{DataStoreModel::editable}
 	bool isEditable() const;
 
-	//! @inherit{QAbstractListModel::headerData}
+	//! @inherit{QAbstractTableModel::headerData}
 	QVariant headerData(int section, Qt::Orientation orientation, int role = Qt::DisplayRole) const override;
-	//! @inherit{QAbstractListModel::rowCount}
+	//! @inherit{QAbstractTableModel::rowCount}
 	int rowCount(const QModelIndex &parent = QModelIndex()) const override;
+	//! @inherit{QAbstractTableModel::columnCount}
 	int columnCount(const QModelIndex &parent) const override;
-	//! @inherit{QAbstractListModel::canFetchMore}
+	//! @inherit{QAbstractTableModel::canFetchMore}
 	bool canFetchMore(const QModelIndex &parent) const override;
-	//! @inherit{QAbstractListModel::fetchMore}
+	//! @inherit{QAbstractTableModel::fetchMore}
 	void fetchMore(const QModelIndex &parent) override;
 
+	//! @inherit{QAbstractTableModel::index}
 	QModelIndex index(int row, int column = 0, const QModelIndex &parent = QModelIndex()) const override;
 	//! Returns the index of the item with the given id
 	Q_INVOKABLE QModelIndex idIndex(const QString &id) const;
@@ -63,9 +65,9 @@ class Q_DATASYNC_EXPORT DataStoreModel : public QAbstractTableModel
 	template <typename T>
 	inline T key(const QModelIndex &index) const;
 
-	//! @inherit{QAbstractListModel::data}
+	//! @inherit{QAbstractTableModel::data}
 	QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
-	//! @inherit{QAbstractListModel::setData}
+	//! @inherit{QAbstractTableModel::setData}
 	bool setData(const QModelIndex &index, const QVariant &value, int role) override;
 
 	//! Returns the object at the given index
@@ -85,18 +87,24 @@ class Q_DATASYNC_EXPORT DataStoreModel : public QAbstractTableModel
 	template <typename T>
 	T loadObject(const QModelIndex &index) const;
 
-	//! @inherit{QAbstractListModel::flags}
+	//! @inherit{QAbstractTableModel::flags}
 	Qt::ItemFlags flags(const QModelIndex &index) const override;
-	//! @inherit{QAbstractListModel::roleNames}
+	//! @inherit{QAbstractTableModel::roleNames}
 	QHash<int, QByteArray> roleNames() const override;
 
+	//! Add a new column with the given title
 	int addColumn(const QString &text);
+	//! Add a new column and set the given property as its Qt::DisplayRole
 	int addColumn(const QString &text, const char *propertyName);
+	//! Adds the given property as a new role to the given column
 	void addRole(int column, int role, const char *propertyName);
+	//! Removes all customly added columns and roles
+	void clearColumns();
 
 public Q_SLOTS:
 	//! @writeAcFn{DataStoreModel::typeId}
 	void setTypeId(int typeId); //MAJOR merge methods
+	//! @writeAcFn{DataStoreModel::typeId}
 	void setTypeId(int typeId, bool resetColumns);
 	//! @writeAcFn{DataStoreModel::editable}
 	void setEditable(bool editable);
@@ -107,6 +115,7 @@ public Q_SLOTS:
 Q_SIGNALS:
 	//! Emitted when the underlying DataStore throws an exception
 	void storeError(const QException &exception, QPrivateSignal);
+	//! @notifyAcFn{DataStoreModel::typeId}
 	void typeIdChanged(int typeId, QPrivateSignal);
 	//! @notifyAcFn{DataStoreModel::editable}
 	void editableChanged(bool editable, QPrivateSignal);
diff --git a/src/datasync/datasync.pro b/src/datasync/datasync.pro
@@ -1,7 +1,6 @@
 TARGET = QtDataSync
 
 QT = core jsonserializer sql websockets scxml remoteobjects remoteobjects-private
-#android: QT += androidextras #needed to deploy the android keystore plugin
 
 HEADERS += \
 	qtdatasync_global.h \
diff --git a/src/datasync/defaults.h b/src/datasync/defaults.h
@@ -84,8 +84,11 @@ class Q_DATASYNC_EXPORT Defaults
 	Defaults(const QSharedPointer<DefaultsPrivate> &d);
 	//! Copy constructor
 	Defaults(const Defaults &other);
+	//! Move constructor
 	Defaults(Defaults &&other);
+	//! Copy assignment operator
 	Defaults &operator=(const Defaults &other);
+	//! Move assignment operator
 	Defaults &operator=(Defaults &&other);
 	~Defaults();
 
diff --git a/src/datasync/exception.h b/src/datasync/exception.h
@@ -28,12 +28,12 @@ class Q_DATASYNC_EXPORT Exception : public QException
 	//! Like what, but returns a QString instead of a character array
 	virtual QString qWhat() const;
 	//! @inherit{QException::what}
-	const char *what() const noexcept final; //mark virtual again for doxygen
+	virtual const char *what() const noexcept final; //mark virtual again for doxygen
 
 	//! @inherit{QException::raise}
-	void raise() const override; //mark virtual again for doxygen
+	virtual void raise() const override; //mark virtual again for doxygen
 	//! @inherit{QException::clone}
-	QException *clone() const override; //mark virtual again for doxygen
+	virtual QException *clone() const override; //mark virtual again for doxygen
 
 protected:
 	//! @private
diff --git a/src/datasync/setup.h b/src/datasync/setup.h
@@ -177,7 +177,9 @@ class Q_DATASYNC_EXPORT Setup
 	static bool keystoreAvailable(const QString &provider);
 	//! Returns the default provider to be used based on the current platform and the available providers
 	static QString defaultKeystoreProvider();
+	//! Create and load akeystore instance from the default provider
 	static KeyStore *loadKeystore(QObject *parent = nullptr, const QString &setupName = DefaultSetup);
+	//! Create and load akeystore instance from the given provider
 	static KeyStore *loadKeystore(const QString &provider, QObject *parent = nullptr, const QString &setupName = DefaultSetup);
 
 	Setup();
@@ -288,9 +290,13 @@ class Q_DATASYNC_EXPORT Setup
 	//! @resetAcFn{Setup::cipherKeySize}
 	Setup &resetCipherKeySize();
 
+	//! Sets an account to be imported on creation of the instance
 	Setup &setAccount(const QJsonObject &importData, bool keepData = false, bool allowFailure = false);
+	//! @copydoc Setup::setAccount(const QJsonObject &, bool, bool)
 	Setup &setAccount(const QByteArray &importData, bool keepData = false, bool allowFailure = false);
+	//! @copybrief Setup::setAccount(const QJsonObject &, bool, bool)
 	Setup &setAccountTrusted(const QJsonObject &importData, const QString &password, bool keepData = false, bool allowFailure = false);
+	//! @copydoc Setup::setAccountTrusted(const QJsonObject &, const QString &, bool, bool)
 	Setup &setAccountTrusted(const QByteArray &importData, const QString &password, bool keepData = false, bool allowFailure = false);
 
 	//! Creates a datasync instance from this setup with the given name
diff --git a/src/datasync/translations/qtdatasync_de.ts b/src/datasync/translations/qtdatasync_de.ts
diff --git a/src/datasync/translations/qtdatasync_template.ts b/src/datasync/translations/qtdatasync_template.ts
diff --git a/src/plugins/keystores/keystores.pro b/src/plugins/keystores/keystores.pro
diff --git a/tests/auto/datasync/IntegrationTest/tst_integration.cpp b/tests/auto/datasync/IntegrationTest/tst_integration.cpp
