docs(mps-sync-plugin-lib): document the classes in the org.modelix.mp…

…s.sync.util package

mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/util/BooleanUtil.kt

@@ -19,11 +19,23 @@ package org.modelix.mps.sync.util
 import org.modelix.kotlin.utils.UnstableModelixFeature
 import java.text.ParseException
 
-@UnstableModelixFeature(reason = "The new modelix MPS plugin is under construction", intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.")
+/**
+ * A workaround util class for extension methods of String.
+ */
+@UnstableModelixFeature(
+    reason = "The new modelix MPS plugin is under construction",
+    intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.",
+)
 object BooleanUtil {
 
     /**
-     * Drop-in replacement, because String.toStringBoolean() does not compile
+     * Drop-in replacement, because [String.toBooleanStrict] does not compile.
+     *
+     * @throws ParseException if [value] is not a boolean.
+     *
+     * @param value the [String] to be converted to a [Boolean].
+     *
+     * @see [String.toBooleanStrict].
      */
     @Throws(ParseException::class)
     fun toBooleanStrict(value: String) =

mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/util/CompletableFutureExt.kt

@@ -19,7 +19,19 @@ package org.modelix.mps.sync.util
 import org.modelix.kotlin.utils.UnstableModelixFeature
 import java.util.concurrent.CompletableFuture
 
-@UnstableModelixFeature(reason = "The new modelix MPS plugin is under construction", intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.")
+/**
+ * An extension method to glue / bind two [CompletableFuture]s together. If this [CompletableFuture] future completes,
+ * then [other] will also complete with the same result. If this [CompletableFuture] fails with a [Throwable], then
+ * [other] will fail with the same [Throwable].
+ *
+ * @param other the other [CompletableFuture] to which we glue this [CompletableFuture].
+ *
+ * @return this.
+ */
+@UnstableModelixFeature(
+    reason = "The new modelix MPS plugin is under construction",
+    intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.",
+)
 fun CompletableFuture<Any?>.bindTo(other: CompletableFuture<Any?>): CompletableFuture<Any?> {
     this.handle { result, throwable ->
         if (throwable != null) {
@@ -31,7 +43,15 @@ fun CompletableFuture<Any?>.bindTo(other: CompletableFuture<Any?>): CompletableF
     return this
 }
 
-@UnstableModelixFeature(reason = "The new modelix MPS plugin is under construction", intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.")
+/**
+ * Completes this with null.
+ *
+ * @return this.
+ */
+@UnstableModelixFeature(
+    reason = "The new modelix MPS plugin is under construction",
+    intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.",
+)
 fun CompletableFuture<Any?>.completeWithDefault(): CompletableFuture<Any?> {
     this.complete(null)
     return this

mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/util/SynchronizedCollections.kt

@@ -19,8 +19,20 @@ package org.modelix.mps.sync.util
 import org.modelix.kotlin.utils.UnstableModelixFeature
 import java.util.Collections
 
-@UnstableModelixFeature(reason = "The new modelix MPS plugin is under construction", intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.")
+/**
+ * @return a [MutableMap] wrapped by [Collections.synchronizedMap].
+ */
+@UnstableModelixFeature(
+    reason = "The new modelix MPS plugin is under construction",
+    intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.",
+)
 fun <K, V> synchronizedMap(): MutableMap<K, V> = Collections.synchronizedMap(mutableMapOf<K, V>())
 
-@UnstableModelixFeature(reason = "The new modelix MPS plugin is under construction", intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.")
+/**
+ * @return a [MutableSet] wrapped by [Collections.synchronizedSet].
+ */
+@UnstableModelixFeature(
+    reason = "The new modelix MPS plugin is under construction",
+    intendedFinalization = "This feature is finalized when the new sync plugin is ready for release.",
+)
 fun <K> synchronizedLinkedHashSet(): MutableSet<K> = Collections.synchronizedSet(LinkedHashSet<K>())

mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/util/WaitForSubtaskCompletionUtil.kt

@@ -19,20 +19,28 @@ package org.modelix.mps.sync.util
 import org.modelix.kotlin.utils.UnstableModelixFeature
 import org.modelix.mps.sync.tasks.ContinuableSyncTask
 import org.modelix.mps.sync.tasks.FuturesWaitQueue
+import org.modelix.mps.sync.tasks.SyncLock
+import org.modelix.mps.sync.tasks.SyncTask
 import java.util.concurrent.CompletableFuture
 
 /**
- * Iterates through each element of the Collection, and calls the `continuableSyncTaskProducer` function on them. I.e.
+ * Iterates through each element of the Collection, and calls the [continuableSyncTaskProducer] function on them. I.e.
  * a synchronization operation from modelix to MPS or the other way around. After that, waits until all tasks are
  * completed.
  *
  * If any of them fails then it fails the resulting future. Otherwise, it completes the resulting future with null.
  *
- * Suggestion: use this method as the last statement of a short-living SyncTask, possibly without any SyncLocks to
- * avoid busy-waiting on the lock. The continuation of SyncTasks will take care of waiting for all futures to complete.
- * If you run a SyncTask on its own, then you have to manually wait for the task to complete.
+ * Suggestion: use this method as the last statement of a short-living [SyncTask], possibly without any [SyncLock]s to
+ * avoid busy-waiting on the lock. The continuation of [SyncTask]s will take care of waiting for all futures to
+ * complete. If you run a [SyncTask] on its own, then you have to manually wait for the task to complete.
  *
- *  @param collectResults if true, then collects the Collection<Any?> results of futureProducer
+ * @param futuresWaitQueue a queue to help scheduling the continuation [SyncTask]s.
+ * @param collectResults if true, then collects the Collection<Any?> results of each [continuableSyncTaskProducer].
+ * @param continuableSyncTaskProducer an action that receives an item from the Collection and creates a
+ * [ContinuableSyncTask] from it (most commonly as a by-product).
+ *
+ * @return a [ContinuableSyncTask] that represents the continuation of all [SyncTask]s that were created for each item
+ * of the Collection.
  */
 @UnstableModelixFeature(
     reason = "The new modelix MPS plugin is under construction",
@@ -46,17 +54,23 @@ internal fun <T> Collection<T>.waitForCompletionOfEachTask(
     this.asIterable().waitForCompletionOfEachTask(futuresWaitQueue, collectResults, continuableSyncTaskProducer)
 
 /**
- * Iterates through each element of the Iterable, and calls the `continuableSyncTaskProducer` function on them. I.e.
+ * Iterates through each element of the Iterable, and calls the [continuableSyncTaskProducer] function on them. I.e.
  * a synchronization operation from modelix to MPS or the other way around. After that, waits until all tasks are
  * completed.
  *
  * If any of them fails then it fails the resulting future. Otherwise, it completes the resulting future with null.
  *
- * Suggestion: use this method as the last statement of a short-living SyncTask, possibly without any SyncLocks to
- * avoid busy-waiting on the lock. The continuation of SyncTasks will take care of waiting for all futures to complete.
- * If you run a SyncTask on its own, then you have to manually wait for the task to complete.
+ * Suggestion: use this method as the last statement of a short-living [SyncTask], possibly without any [SyncLock]s to
+ * avoid busy-waiting on the lock. The continuation of [SyncTask]s will take care of waiting for all futures to
+ * complete. If you run a [SyncTask] on its own, then you have to manually wait for the task to complete.
+ *
+ * @param futuresWaitQueue a queue to help scheduling the continuation [SyncTask]s.
+ * @param collectResults if true, then collects the Iterable<Any?> results of each [continuableSyncTaskProducer].
+ * @param continuableSyncTaskProducer an action that receives an item from the Iterable and creates a
+ * [ContinuableSyncTask] from it (most commonly as a by-product).
  *
- *  @param collectResults if true, then collects the Iterable<Any?> results of futureProducer
+ * @return a [ContinuableSyncTask] that represents the continuation of all [SyncTask]s that were created for each item
+ * of the Iterable.
  */
 @UnstableModelixFeature(
     reason = "The new modelix MPS plugin is under construction",
@@ -72,16 +86,22 @@ internal fun <T> Iterable<T>.waitForCompletionOfEachTask(
     }
 
 /**
- * Iterates through each element of the Iterable, and calls the `futureProducer` function on them. After that,
+ * Iterates through each element of the Iterable, and calls the [futureProducer] function on them. After that,
  * waits until all futures are completed.
  *
  * If any of them fails then it fails the resulting future. Otherwise, it completes the resulting future with null.
  *
- * Suggestion: use this method as the last statement of a short-living SyncTask, possibly without any SyncLocks to
- * avoid busy-waiting on the lock. The continuation of SyncTasks will take care of waiting for all futures to complete.
- * If you run a SyncTask on its own, then you have to manually wait for the task to complete.
+ * Suggestion: use this method as the last statement of a short-living [SyncTask], possibly without any [SyncLock]s to
+ * avoid busy-waiting on the lock. The continuation of [SyncTask]s will take care of waiting for all futures to
+ * complete. If you run a [SyncTask] on its own, then you have to manually wait for the task to complete.
+ *
+ * @param futuresWaitQueue a queue to help scheduling the continuation [SyncTask]s.
+ * @param collectResults if true, then collects the Iterable<Any?> results of [futureProducer] into an Iterable<Any?>.
+ * @param futureProducer an action that receives an item from the Iterable and creates a [CompletableFuture] from it
+ * (most commonly as a by-product).
  *
- * @param collectResults if true, then collects the Iterable<Any?> results of futureProducer into an Iterable<Any?>
+ * @return a [ContinuableSyncTask] that represents the continuation of all [SyncTask]s that were created for each item
+ * of the Iterable.
  */
 @UnstableModelixFeature(
     reason = "The new modelix MPS plugin is under construction",