docs(model-sync-lib): added documentation

Author: mhuster23

model-sync-lib/src/commonMain/kotlin/org/modelix/model/sync/ModelExporter.kt

@@ -5,8 +5,15 @@ import org.modelix.model.api.serialize
 import org.modelix.model.data.NodeData
 import org.modelix.model.data.associateWithNotNull
 
+/**
+ * A ModelExporter exports a node and its subtree in bulk.
+ */
 expect class ModelExporter(root: INode)
 
+/**
+ * Returns a [NodeData] representation of the receiver node as it would be exported by a [ModelExporter].
+ * This function is recursively called on the node's children.
+ */
 fun INode.asExported() : NodeData {
     val idKey = NodeData.idPropertyKey
     return NodeData(

model-sync-lib/src/commonMain/kotlin/org/modelix/model/sync/ModelImporter.kt

@@ -4,12 +4,27 @@ import org.modelix.model.api.*
 import org.modelix.model.data.ModelData
 import org.modelix.model.data.NodeData
 
+/**
+ * A ModelImporter updates an existing [INode] and its subtree based on a [ModelData] specification.
+ *
+ * The import is incremental.
+ * Instead of simply overwriting the existing model, only a minimal amount of operations is used.
+ *
+ * Properties, references, and child links are synchronized for this node and all of its (in-)direct children.
+ *
+ * @param root the root node to be updated
+ */
 class ModelImporter(private val root: INode) {
 
     private val originalIdToExisting: MutableMap<String, INode> = mutableMapOf()
     private val postponedReferences = ArrayList<() -> Unit>()
     private val nodesToRemove = HashSet<INode>()
-    
+
+    /**
+     * Incrementally updates this importers root based on the provided [ModelData] specification.
+     *
+     * @param data the model specification
+     */
     fun import(data: ModelData) {
         originalIdToExisting.clear()
         postponedReferences.clear()

model-sync-lib/src/jsMain/kotlin/org/modelix/model/sync/ModelExporter.kt

@@ -3,5 +3,11 @@ package org.modelix.model.sync
 import org.modelix.model.api.INode
 
 actual class ModelExporter actual constructor(private val root: INode) {
+
+    /**
+     * Triggers a bulk export of this ModelExporter's root node and its (in-)direct children.
+     *
+     * @return exported node
+     */
     fun export() = root.asExported()
 }

model-sync-lib/src/jvmMain/kotlin/org/modelix/model/sync/ModelExporter.kt

@@ -5,6 +5,12 @@ import org.modelix.model.data.ModelData
 import java.io.File
 
 actual class ModelExporter actual constructor(private val root: INode) {
+
+    /**
+     * Triggers a bulk export of this ModelExporter's root node and its (in-)direct children into the specified file.
+     *
+     * @param outputFile target file of the export
+     */
     fun export(outputFile: File) {
         val modelData = ModelData(root = root.asExported())
         outputFile.parentFile.mkdirs()

model-sync-lib/src/jvmMain/kotlin/org/modelix/model/sync/PlatformSpecific.kt

@@ -3,6 +3,14 @@ package org.modelix.model.sync
 import org.modelix.model.data.ModelData
 import java.io.File
 
+/**
+ * Incrementally updates the root of the receiver [ModelImporter]
+ * based on the [ModelData] specification contained in the given file.
+ *
+ * @param jsonFile json file containing the model specification
+ *
+ * @throws IllegalArgumentException if the file is not a json file or the file does not exist.
+ */
 fun ModelImporter.import(jsonFile: File) {
     require(jsonFile.exists())
     require(jsonFile.extension == "json")