added migrationhelper doc

Author: Skycoder42

doc/migrationhelper.dox

@@ -0,0 +1,46 @@
+/*!
+@class QtDataSync::MigrationHelper
+
+If you used QtDataSync below version 4 before, you will have to use this class to migrate the data
+from that old datasync to the current new one, as they are not compatible. This is what this class
+is used for.
+
+The migration is performed asynchronously once started and cannot be stopped. To start a
+migration, use startMigration().
+
+@sa MigrationHelper::startMigration, MigrationHelper::migrationDone
+*/
+
+/*!
+@fn QtDataSync::MigrationHelper::MigrationHelper(QObject *)
+
+@param parent The parent object
+@throws SetupDoesNotExistException Thrown if the default setup was not created yet
+*/
+
+/*!
+@fn QtDataSync::MigrationHelper::MigrationHelper(const QString &, QObject *)
+
+@param setupName The name of the setup to connect to
+@param parent The parent object
+@throws SetupDoesNotExistException Thrown if the given setup was not created yet
+*/
+
+/*!
+@fn QtDataSync::MigrationHelper::startMigration
+
+@param storageDir The old datasync directory to import the data from
+@param flags Flags to configure what and how to migrate the data
+
+The `storageDir` must be the directory that the old datasync used as storage directory. If you
+did not change it, the DefaultOldStorageDir constant can be used, as it points to the previous
+default datasync storage dir.
+
+Migration is performed asynchronously with the status beeing reported via the signals. Errors,
+warnings and other stuff is logged as usual. Use the `qtdatasync.<setupName>.migration` logging
+category to filter for it.
+
+@sa MigrationHelper::MigrationFlag, MigrationHelper::DefaultOldStorageDir,
+MigrationHelper::migrationDone, MigrationHelper::migrationPrepared,
+MigrationHelper::migrationProgress,
+*/

src/datasync/migrationhelper.cpp

@@ -169,8 +169,6 @@ void MigrationRunnable::run()
 				 currentSettings, QStringLiteral("connector/") + RemoteConnector::keyRemoteEnabled);
 		copyConf(oldSettings, QStringLiteral("RemoteConnector/remoteUrl"),
 				 currentSettings, QStringLiteral("connector/") + RemoteConnector::keyRemoteUrl);
-//		copyConf(oldSettings, QStringLiteral("RemoteConnector/verifyPeer"),
-//				 currentSettings, QStringLiteral("connector/remote/verifyPeer")); //TODO add?
 		copyConf(oldSettings, QStringLiteral("RemoteConnector/sharedSecret"),
 				 currentSettings, QStringLiteral("connector/") + RemoteConnector::keyRemoteAccessKey);
 

src/datasync/migrationhelper.h

@@ -9,36 +9,46 @@
 namespace QtDataSync {
 
 class MigrationHelperPrivate;
+//! A helper class to migrate data from DataSync 3.0 to this version
 class Q_DATASYNC_EXPORT MigrationHelper : public QObject
 {
 	Q_OBJECT
 
 public:
+	//! Flags to configure what and how should be migrated
 	enum MigrationFlag {
-		MigrateData = 0x01,
-		MigrateChanged = (0x02 | MigrateData),
-		MigrateRemoteConfig = 0x04,
-		MigrateAll = (MigrateData | MigrateChanged | MigrateRemoteConfig),
-
-		MigrateWithCleanup = 0x08,
-		MigrateOverwriteConfig = 0x10,
-		MigrateOverwriteData = 0x20
+		MigrateData = 0x01, //!< Migrate actual stored data
+		MigrateChanged = (0x02 | MigrateData), //!< Migrate the changed state of that data
+		MigrateRemoteConfig = 0x04, //!< Migrate the connection configuration
+
+		MigrateWithCleanup = 0x08, //!< Remove all old data after a successful migration
+		MigrateOverwriteConfig = 0x10, //!< Overwrite existing configurations with the migrated remote config
+		MigrateOverwriteData = 0x20, //!< Overwrite existing data with the migrated data
+
+		MigrateDefault = (MigrateData | MigrateRemoteConfig | MigrateWithCleanup) //!< The default flags when leaving out the parameter
 	};
 	Q_DECLARE_FLAGS(MigrationFlags, MigrationFlag)
 	Q_FLAG(MigrationFlags)
 
+	//! The previous default path where data was stored
 	static const QString DefaultOldStorageDir;
 
+	//! Default constructor, uses the default setup
 	explicit MigrationHelper(QObject *parent = nullptr);
+	//! Constructor with an explicit setup
 	explicit MigrationHelper(const QString &setupName, QObject *parent = nullptr);
 	~MigrationHelper();
 
 public Q_SLOTS:
-	void startMigration(const QString &storageDir = DefaultOldStorageDir, MigrationFlags flags = MigrationFlags(MigrateAll) | MigrateWithCleanup);
+	//! Start the migration process from the given directory with flags
+	void startMigration(const QString &storageDir = DefaultOldStorageDir, MigrationFlags flags = MigrateDefault);
 
 Q_SIGNALS:
+	//! Is emitted when the number of migrate operations has been determined
 	void migrationPrepared(int operations);
+	//! Is emitted for every successful migration step done to give a progress
 	void migrationProgress(int current);
+	//! Is emitted when the migration has been finished
 	void migrationDone(bool ok);
 
 private: