Syncer: rename methods for clarity, add KDoc

app/src/androidTest/kotlin/at/bitfire/davdroid/sync/SyncerTest.kt

@@ -175,10 +175,10 @@ class SyncerTest {
         override fun prepare(provider: ContentProviderClient): Boolean =
             true
 
-        override fun localSyncCollections(provider: ContentProviderClient): List<LocalTestCollection> =
+        override fun getLocalCollections(provider: ContentProviderClient): List<LocalTestCollection> =
             emptyList()
 
-        override fun getSyncCollections(serviceId: Long): List<Collection> =
+        override fun getDbSyncCollections(serviceId: Long): List<Collection> =
             emptyList()
 
         override fun create(provider: ContentProviderClient, remoteCollection: Collection): LocalTestCollection =

app/src/main/kotlin/at/bitfire/davdroid/sync/AddressBookSyncer.kt

@@ -48,15 +48,15 @@ class AddressBookSyncer @AssistedInject constructor(
         get() = ContactsContract.AUTHORITY // Address books use the contacts authority for sync
 
 
-    override fun localSyncCollections(provider: ContentProviderClient): List<LocalAddressBook> =
+    override fun getLocalCollections(provider: ContentProviderClient): List<LocalAddressBook> =
         serviceRepository.getByAccountAndType(account.name, serviceType)?.let { service ->
             // Get _all_ address books; Otherwise address book accounts of unchecked address books will not be removed
             collectionRepository.getByService(service.id).mapNotNull { collection ->
                 LocalAddressBook.findByCollection(context, provider, collection.id)
             }
         }.orEmpty()
 
-    override fun getSyncCollections(serviceId: Long): List<Collection> =
+    override fun getDbSyncCollections(serviceId: Long): List<Collection> =
         collectionRepository.getByServiceAndSync(serviceId)
 
     override fun update(localCollection: LocalAddressBook, remoteCollection: Collection) {

app/src/main/kotlin/at/bitfire/davdroid/sync/CalendarSyncer.kt

@@ -39,7 +39,7 @@ class CalendarSyncer @AssistedInject constructor(
         get() = CalendarContract.AUTHORITY
 
 
-    override fun localSyncCollections(provider: ContentProviderClient): List<LocalCalendar>
+    override fun getLocalCollections(provider: ContentProviderClient): List<LocalCalendar>
         = AndroidCalendar.find(account, provider, LocalCalendar.Factory, "${CalendarContract.Calendars.SYNC_EVENTS}!=0", null)
 
     override fun prepare(provider: ContentProviderClient): Boolean {
@@ -51,7 +51,7 @@ class CalendarSyncer @AssistedInject constructor(
         return true
     }
 
-    override fun getSyncCollections(serviceId: Long): List<Collection> =
+    override fun getDbSyncCollections(serviceId: Long): List<Collection> =
         collectionRepository.getSyncCalendars(serviceId)
 
     override fun syncCollection(provider: ContentProviderClient, localCollection: LocalCalendar, remoteCollection: Collection) {

app/src/main/kotlin/at/bitfire/davdroid/sync/JtxSyncer.kt

@@ -45,7 +45,7 @@ class JtxSyncer @AssistedInject constructor(
         get() = TaskProvider.ProviderName.JtxBoard.authority
 
 
-    override fun localSyncCollections(provider: ContentProviderClient): List<LocalJtxCollection>
+    override fun getLocalCollections(provider: ContentProviderClient): List<LocalJtxCollection>
         = JtxCollection.find(account, provider, context, LocalJtxCollection.Factory, null, null)
 
     override fun prepare(provider: ContentProviderClient): Boolean {
@@ -70,7 +70,7 @@ class JtxSyncer @AssistedInject constructor(
         return true
     }
 
-    override fun getSyncCollections(serviceId: Long): List<Collection> =
+    override fun getDbSyncCollections(serviceId: Long): List<Collection> =
         collectionRepository.getSyncJtxCollections(serviceId)
 
     override fun update(localCollection: LocalJtxCollection, remoteCollection: Collection) {

app/src/main/kotlin/at/bitfire/davdroid/sync/Syncer.kt

@@ -96,7 +96,7 @@ abstract class Syncer<CollectionType: LocalCollection<*>>(
 
         // Find collections in database and provider which should be synced (are sync-enabled)
         val dbCollections = getSyncEnabledCollections()
-        val localCollections = localSyncCollections(provider).toMutableList()
+        val localCollections = getLocalCollections(provider).toMutableList()
 
         // Update/delete local collections and determine new (unknown) remote collections
         val newDbCollections = updateCollections(localCollections, dbCollections)
@@ -119,7 +119,7 @@ abstract class Syncer<CollectionType: LocalCollection<*>>(
     internal fun getSyncEnabledCollections(): Map<HttpUrl, Collection> {
         val dbCollections = mutableMapOf<HttpUrl, Collection>()
         serviceRepository.getByAccountAndType(account.name, serviceType)?.let { service ->
-            for (dbCollection in getSyncCollections(service.id))
+            for (dbCollection in getDbSyncCollections(service.id))
                 dbCollections[dbCollection.url] = dbCollection
         }
         return dbCollections
@@ -197,39 +197,45 @@ abstract class Syncer<CollectionType: LocalCollection<*>>(
     open fun prepare(provider: ContentProviderClient): Boolean = true
 
     /**
-     * Get the local collections to be updated after sync
+     * Gets all local collections (not from the database, but from the content provider).
+     *
+     * [Syncer] will remove collections which are returned by this method, but not by
+     * [getDbSyncCollections], and add collections which are returned by [getDbSyncCollections], but not by this method.
      *
      * @param provider Content provider to access local collections
      * @return Local collections to be updated
      */
-    abstract fun localSyncCollections(provider: ContentProviderClient): List<CollectionType>
+    abstract fun getLocalCollections(provider: ContentProviderClient): List<CollectionType>
 
     /**
-     * Get the local database collections which are sync-enabled (should by synchronized)
+     * Get the local database collections which are sync-enabled (should by synchronized).
+     *
+     * [Syncer] will remove collections which are returned by [getLocalCollections], but not by
+     * this method, and add collections which are returned by this method, but not by [getLocalCollections].
      *
      * @param serviceId The CalDAV or CardDAV service (account) to be synchronized
      * @return Database collections to be synchronized
      */
-    abstract fun getSyncCollections(serviceId: Long): List<Collection>
+    abstract fun getDbSyncCollections(serviceId: Long): List<Collection>
 
     /**
-     * Update an existing local collection with remote collection information
+     * Updates an existing local collection (in the content provider) with remote collection information (from the DB).
      *
      * @param localCollection The local collection to be updated
      * @param remoteCollection The new remote collection information
      */
     abstract fun update(localCollection: CollectionType, remoteCollection: Collection)
 
     /**
-     * Create a new local collection from remote collection information
+     * Creates a new local collection (in the content provider) from remote collection information (from the DB).
      *
      * @param provider The content provider client to create the local collection
      * @param remoteCollection The remote collection to be created locally
      */
     abstract fun create(provider: ContentProviderClient, remoteCollection: Collection): CollectionType
 
     /**
-     * Synchronise local with remote collection contents
+     * Synchronizes local with remote collection contents.
      *
      * @param provider The content provider client to access the local collection to be updated
      * @param localCollection The local collection to be synchronized
@@ -239,9 +245,10 @@ abstract class Syncer<CollectionType: LocalCollection<*>>(
     abstract fun syncCollection(provider: ContentProviderClient, localCollection: CollectionType, remoteCollection: Collection)
 
     /**
-     * Prepares the sync
-     * - acquires content provider
-     * - handles occurring sync errors
+     * Prepares the sync:
+     *
+     * - acquire content provider
+     * - handle occurring sync errors
      */
     operator fun invoke() {
         logger.log(Level.INFO, "$authority sync of $account initiated", extras.joinToString(", "))

app/src/main/kotlin/at/bitfire/davdroid/sync/TaskSyncer.kt

@@ -43,7 +43,7 @@ class TaskSyncer @AssistedInject constructor(
     override val serviceType: String
         get() = Service.TYPE_CALDAV
 
-    override fun localSyncCollections(provider: ContentProviderClient): List<LocalTaskList>
+    override fun getLocalCollections(provider: ContentProviderClient): List<LocalTaskList>
         = DmfsTaskList.find(account, LocalTaskList.Factory, provider, providerName, "${TaskLists.SYNC_ENABLED}!=0", null)
 
     override fun prepare(provider: ContentProviderClient): Boolean {
@@ -68,7 +68,7 @@ class TaskSyncer @AssistedInject constructor(
         return true
     }
 
-    override fun getSyncCollections(serviceId: Long): List<Collection> =
+    override fun getDbSyncCollections(serviceId: Long): List<Collection> =
         collectionRepository.getSyncTaskLists(serviceId)
 
     override fun update(localCollection: LocalTaskList, remoteCollection: Collection) {