added android class docs

Author: Skycoder42

doc/androidbackgroundservice.dox

@@ -0,0 +1,141 @@
+/*!
+@class QtDataSync::AndroidBackgroundService
+
+This service can be used as Android service to create a background synchronizations service
+without much effort. However, a few additional setup steps are needed. This class only extends
+the QtService implementation of an android service to add the synchronization aspect.
+
+@warning This class alone is **not** sufficient to make synchronization possible. Have a look at
+the @ref android_sync_guide to learn how to add background synchronization to your project.
+
+@sa AndroidSyncControl, QtService::Service, @ref qtservice_backends_android
+*/
+
+/*!
+@property QtDataSync::AndroidBackgroundService::waitFullSync
+
+@default{`true`}
+
+If set to true, the serivce will internally call SyncManager::runOnSynchronized() with the
+onSyncCompleted() as handler. If disable, SyncManager::runOnDownloaded() is used instead. Check
+the documentation of these two methods.
+
+@accessors{
+	@readAc{waitFullSync()}
+	@writeAc{setWaitFullSync()}
+	@notifyAc{waitFullSyncChanged()}
+}
+
+@sa AndroidBackgroundService::onSyncCompleted, SyncManager::runOnSynchronized,
+SyncManager::runOnDownloaded
+*/
+
+/*!
+@fn QtDataSync::AndroidBackgroundService::setupName
+
+@returns The name of the setup
+
+The default implementation returns `QtDataSync::DefaultSetup`. You can override the method if you
+need the service to create the setup under a different name.
+
+@sa QtDataSync::DefaultSetup, AndroidBackgroundService::prepareSetup
+*/
+
+/*!
+@fn QtDataSync::AndroidBackgroundService::prepareSetup
+
+@param setup The setup to be prepared
+
+You should override this method to configure the setup before creation (i.e. set properties on it).
+The default implementation does nothing.
+
+@sa QtDataSync::Setup, AndroidBackgroundService::setupName
+*/
+
+/*!
+@fn QtDataSync::AndroidBackgroundService::onSyncCompleted
+
+@param state The state in which the synchronization finished
+
+This method is called as soon as the datasync instance has finished the data synchronization. You
+can override it to perform additional operations with the data before quitting the service.
+
+The default implementation only calls exitAfterSync() to quit the service gracefully. You must
+do the same in your implementation. You do not have to call it from within the method, but must
+call it eventually. Otherwise it will keep running indefinitely
+
+Possible states can be:
+- Uploading (only if waitFullSync is set to false)
+- Synchronized
+- Error
+- Disconnected
+
+@sa AndroidBackgroundService::waitFullSync, AndroidBackgroundService::exitAfterSync
+*/
+
+/*!
+@fn QtDataSync::AndroidBackgroundService::exitAfterSync
+
+Call this method if you reimplement onSyncCompleted(). It will quit the service gracefully,
+honoring the order of start commands, if multiple have been used. Internally, this method calls
+stopSelf() with the most recently used startId of a BackgroundSyncAction.
+
+@sa AndroidBackgroundService::onSyncCompleted, AndroidBackgroundService::stopSelf,
+AndroidBackgroundService::BackgroundSyncAction
+*/
+
+/*!
+@fn QtDataSync::AndroidBackgroundService::onStartCommand
+
+@param intent The intent that was used to start the service
+@param flags The flags that were used to start the service
+@param startId The id of this start request
+@returns A value allowed by android to indicate the servies state
+
+This method is registered within QtService via QtService::Service::addCallback. Check
+@ref qtservice_backends_android documentation for details on the method itself. Its bascially just
+a forwarding of the Android Service method.
+
+Only implement this if you need to do custom stuff here. You should always call this base
+implementation in your overload, as this method internally handles the synchronization intents.
+
+@attention This method is called synchronously on the android thread. This means you should not
+interact with service class at all. Only use queued invokes to schedule things to be done on
+the actual main thread.
+
+@sa @ref qtservice_backends_android, QtService::Service::addCallback,
+AndroidBackgroundService::stopSelf,
+[android.app.Service.onStartCommand](https://developer.android.com/reference/android/app/Service.html#onStartCommand(android.content.Intent,%20int,%20int))
+*/
+
+/*!
+@fn QtDataSync::AndroidBackgroundService::createForegroundNotification
+
+@returns An Android
+[Notification](https://developer.android.com/reference/android/app/Notification) object, ready to
+be presented as foreground notification
+
+You must implement this method to create a working service, as since Android 8, all services that
+want to run must show a foreground notification while running in order to not be killed by the
+system. A basic sample could be the following.
+
+The code to create the notification was first written in java:
+@snippet SvcHelper.java create_notification
+And that method is then simply called from the implementation:
+@snippet syncservice.cpp jni_create_notification
+
+@sa [android.app.Notification](https://developer.android.com/reference/android/app/Notification)
+*/
+
+/*!
+@fn QtDataSync::AndroidBackgroundService::stopSelf
+
+@param startId The id of the start command that was finished and thus is beeing stopped
+@returns true if the service stop was accepted, false if not
+
+Internally this method simply calls stopSelfResult on the android service. You can reimplement
+it if you want to customize how to quit the service.
+
+@sa AndroidBackgroundService::exitAfterSync, AndroidBackgroundService::onStartCommand,
+android.app.Service.stopSelfResult](https://developer.android.com/reference/android/app/Service.html#stopSelfResult(int))
+*/

doc/androidsynccontrol.dox

@@ -0,0 +1,106 @@
+/*!
+@class QtDataSync::AndroidSyncControl
+
+This class is part of the `QtDataSyncAndroid` module, which is only available on the android
+platform. It can be used to configure background synchronization so that your application is able
+to update it's internal data periodically in the background, even if your app is not actively
+used.
+
+@warning This class alone is **not** sufficient to make this possible. You will also have to
+create a service based on AndroidBackgroundService and correctly set up the Manifest and other
+things. Have a look at the @ref android_sync_guide to learn how to add background synchronization
+to your project.
+
+@sa AndroidBackgroundService, @ref android_sync_guide, IosSyncDelegate
+*/
+
+/*!
+@property QtDataSync::AndroidSyncControl::valid
+
+@default{`false`}
+
+Validity basically comes down to whether there is a background service that matches the given
+serviceId. Only if the control is valid, it is possible to actually do anything with this class
+
+@accessors{
+	@readAc{isValid()}
+	@notifyAc{validChanged()}
+}
+
+@sa AndroidSyncControl::serviceId
+*/
+
+/*!
+@property QtDataSync::AndroidSyncControl::serviceId
+
+@default{`"de.skycoder42.qtservice.AndroidService"`}
+
+The JAVA class name (*not* JNI name) of the android service that should be run to perform the
+background synchronization. The class must exist and must be declared as service in your
+AndroidManifest.xml
+
+@accessors{
+	@readAc{serviceId()}
+	@writeAc{setServiceId()}
+	@notifyAc{serviceIdChanged()}
+}
+
+@sa AndroidSyncControl::valid, AndroidBackgroundService, AndroidSyncControl::enabled,
+@ref qtservice_backends_android
+*/
+
+/*!
+@property QtDataSync::AndroidSyncControl::interval
+
+@default{`60` (minutes)}
+
+This value is passed to the operating system to schedule the background synchronization. There
+is no guarantee of exact delivery of those background synchronizations. It is only a suggestion
+to the system. However, android typically keeps the windows limited to twice the length of the
+interval.
+
+@accessors{
+	@readAc{interval()}
+	@readAc{intervalMinutes()}
+	@writeAc{setInterval()}
+	@notifyAc{intervalChanged()}
+}
+
+@sa AndroidSyncControl::serviceId
+*/
+
+@sa AndroidSyncControl::valid, AndroidSyncControl::enabled
+*/
+
+/*!
+@property QtDataSync::AndroidSyncControl::enabled
+
+@default{`false`}
+
+These property directly communicates with the OS and schedules (or unschedules) the task to run
+the service. This means you must always set serviceId and interval first before enabling a service
+
+@attention This property is persisted. This means after changing it and restarting it, the new
+value will be the same as the one you set. This does *not* apply to all other properties. For
+example, after creating this class, it could already return enabled, but the interval property
+might not match the interval the service actually uses.
+
+@accessors{
+	@readAc{isEnabled()}
+	@writeAc{setEnabled()}
+}
+
+@sa AndroidSyncControl::serviceId, AndroidSyncControl::interval,
+AndroidSyncControl::triggerSyncNow
+*/
+
+/*!
+@fn QtDataSync::AndroidSyncControl::triggerSyncNow
+
+@returns true, if the operating system accepted the synchronization request, false if not
+
+@note This only tells the OS to start the service specified by serviceId. It does not report back
+whether the service was actually correctly started or wether it finished gracefully.
+
+@sa AndroidSyncControl::enabled
+*/

doc/makedoc.sh

@@ -42,7 +42,9 @@ fi
 
 for tagFile in $(find "$qtDocs" -name *.tags); do
 	if [ $(basename "$tagFile") == "qtjsonserializer.tags" ]; then
-		echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QJsonSerializer\"" >> $doxyRes
+		echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtJsonSerializer\"" >> $doxyRes
+	elif [ $(basename "$tagFile") == "qtservice.tags" ]; then
+		echo "TAGFILES += \"$tagFile=https://skycoder42.github.io/QtService\"" >> $doxyRes
 	elif [ $(basename "$tagFile") != "qtdatasync.tags" ]; then
 		echo "TAGFILES += \"$tagFile=https://doc.qt.io/qt-5\"" >> $doxyRes
 	fi

examples/datasync/AndroidSync/android/src/de/skycoder42/qtdatasync/sample/androidsync/SvcHelper.java

@@ -15,19 +15,20 @@
 public class SvcHelper {
 	private static final String ForegroundChannelId = "de.skycoder42.qtdatasync.sample.androidsync.notify";
 
+	//! [create_notification]
 	public static Notification createFgNotification(Context context) {
-		NotificationCompat.Builder builder = new NotificationCompat.Builder(context, ForegroundChannelId)
+		return new NotificationCompat.Builder(context, ForegroundChannelId)
 			.setContentTitle("AndroidSync Synchronization Service")
 			.setContentText("Synchronizing…")
 			.setContentInfo("AndroidSync")
 			.setLargeIcon(BitmapFactory.decodeResource(context.getResources(), R.drawable.icon))
 			.setSmallIcon(R.drawable.icon)
 			.setLocalOnly(true)
 			.setOngoing(true)
-			.setCategory(NotificationCompat.CATEGORY_SERVICE);
-
-		return builder.build();
+			.setCategory(NotificationCompat.CATEGORY_SERVICE)
+			.build();
 	}
+	//! [create_notification]
 
 	public static void registerNotificationChannel(Context context) {
 		if(Build.VERSION.SDK_INT < Build.VERSION_CODES.O)

examples/datasync/AndroidSync/syncservice.cpp

@@ -11,10 +11,12 @@ void SyncService::onSyncCompleted(QtDataSync::SyncManager::SyncState state)
 	exitAfterSync();
 }
 
+//! [jni_create_notification]
 QAndroidJniObject SyncService::createForegroundNotification()
 {
 	return QAndroidJniObject::callStaticObjectMethod("de/skycoder42/qtdatasync/sample/androidsync/SvcHelper",
 													 "createFgNotification",
 													 "(Landroid/content/Context;)Landroid/app/Notification;",
 													 QtAndroid::androidService().object());
 }
+//! [jni_create_notification]

src/datasyncandroid/androidbackgroundservice.h

@@ -15,40 +15,58 @@
 namespace QtDataSync {
 
 class AndroidBackgroundServicePrivate;
+//! An extension of QtService to create a synchronization service for android
 class Q_DATASYNCANDROID_EXPORT AndroidBackgroundService : public QtService::Service // clazy:exclude=ctor-missing-parent-argument
 {
 	Q_OBJECT
 
+	//! Specify whether the service should wait for a full synchronization or only the download
 	Q_PROPERTY(bool waitFullSync READ waitFullSync WRITE setWaitFullSync NOTIFY waitFullSyncChanged)
 
 public:
+	//! The Intent Action used to start the background synchronization
 	static const QString BackgroundSyncAction;
+	//! The Intent Action used to register the service for background synchronization
 	static const QString RegisterSyncAction;
+	//! The ID of the Foreground notification shown by the service while synchronizing
 	static const int ForegroundNotificationId;
 
+	//! Default constructor
 	AndroidBackgroundService(int &argc, char **argv, int = QCoreApplication::ApplicationFlags);
 	~AndroidBackgroundService() override;
 
+	//! @readAcFn{AndroidBackgroundService::waitFullSync}
 	bool waitFullSync() const;
 
 public Q_SLOTS:
+	//! @writeAcFn{AndroidBackgroundService::waitFullSync}
 	void setWaitFullSync(bool waitFullSync);
 
 Q_SIGNALS:
+	//! @notifyAcFn{AndroidBackgroundService::waitFullSync}
 	void waitFullSyncChanged(bool waitFullSync, QPrivateSignal);
 
 protected:
+	//! Returns the name of the setup to be synchronized
 	virtual QString setupName() const;
+	//! Prepares the setup to be synchronized
 	virtual void prepareSetup(Setup &setup);
 
+	//! @inherit{QtService::Service::onStart}
 	CommandResult onStart() override;
+	//! @inherit{QtService::Service::onStop}
 	CommandResult onStop(int &exitCode) override;
 
+	//! Is called by the service as soon the the synchronization has been completed
 	virtual void onSyncCompleted(SyncManager::SyncState state);
+	//! Tells the service to quit itself after a synchronization
 	void exitAfterSync();
 
+	//! Is called on the android thread to deliver the start command
 	virtual int onStartCommand(const QAndroidIntent &intent, int flags, int startId);
+	//! Is called on the android thread to create a foreground notification
 	virtual QAndroidJniObject createForegroundNotification() = 0;
+	//! Is called by the service to stop itself once finished, based on the id it was started with
 	virtual bool stopSelf(int startId);
 
 private Q_SLOTS:

src/datasyncandroid/androidbackgroundservice_p.h

@@ -13,7 +13,7 @@ class AndroidBackgroundServicePrivate
 	SyncManager *manager = nullptr;
 	int startId = -1;
 
-	bool waitFullSync = false;
+	bool waitFullSync = true;
 };
 
 }