docs(mps-sync-plugin-lib): simplify FQN references and direct links i…

…n the header comments
modelix · Oct 9, 2024 · dcc82ae · dcc82ae
1 parent e7da445
commit dcc82ae
Show file tree

Hide file tree

Showing 34 changed files with 187 additions and 151 deletions.
diff --git a/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/SyncServiceImpl.kt b/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/SyncServiceImpl.kt
@@ -7,6 +7,8 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.runBlocking
 import mu.KotlinLogging
+import org.jetbrains.mps.openapi.model.SModel
+import org.jetbrains.mps.openapi.module.SModule
 import org.jetbrains.mps.openapi.module.SRepository
 import org.modelix.kotlin.utils.UnstableModelixFeature
 import org.modelix.model.api.IBranch
@@ -68,8 +70,7 @@ class SyncServiceImpl : ISyncService, InjectableService {
         get() = serviceLocator.branchRegistry
 
     /**
-     * The active [SRepository] to access the [org.jetbrains.mps.openapi.model.SModel]s and
-     * [org.jetbrains.mps.openapi.module.SModule]s in MPS.
+     * The active [SRepository] to access the [SModel]s and [SModule]s in MPS.
      */
     private val mpsRepository: SRepository
         get() = serviceLocator.mpsRepository

diff --git a/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/BindingSortComparator.kt b/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/BindingSortComparator.kt
@@ -35,8 +35,8 @@ class BindingSortComparator : Comparator<IBinding> {
      * @param left one of the [IBinding]s to compare.
      * @param right the other [IBinding] to compare to.
      *
-     * @return if positive, then "left" should be before "right". If negative, then "right" should be before "left". If
-     * zero then the order does not matter.
+     * @return if positive, then [left] should be before [right]. If negative, then [right] should be before [left]. If
+     * zero, then the order does not matter.
      */
     override fun compare(left: IBinding, right: IBinding): Int {
         val leftName = left.name()

diff --git a/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/BindingsRegistry.kt b/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/BindingsRegistry.kt
@@ -22,6 +22,9 @@ import org.jetbrains.mps.openapi.model.SModelId
 import org.jetbrains.mps.openapi.module.SModule
 import org.modelix.kotlin.utils.UnstableModelixFeature
 import org.modelix.mps.sync.IBinding
+import org.modelix.mps.sync.bindings.BindingLifecycleState.ACTIVATE
+import org.modelix.mps.sync.bindings.BindingLifecycleState.ADD
+import org.modelix.mps.sync.bindings.BindingLifecycleState.REMOVE
 import org.modelix.mps.sync.mps.services.InjectableService
 import org.modelix.mps.sync.util.completeWithDefault
 import org.modelix.mps.sync.util.synchronizedLinkedHashSet
@@ -61,7 +64,8 @@ class BindingsRegistry : InjectableService {
     val changedBindings = LinkedBlockingQueue<BindingState>()
 
     /**
-     * Adds a [ModelBinding] to the registry, and puts it in [changedBindings] with the [BindingLifecycleState.ADD] state.
+     * Adds a [ModelBinding] to the registry, and puts it in [changedBindings] with the [BindingLifecycleState.ADD]
+     * state.
      *
      * @param binding the [ModelBinding] to be put in the registry.
      */
@@ -71,7 +75,8 @@ class BindingsRegistry : InjectableService {
     }
 
     /**
-     * Adds a [ModuleBinding] to the registry, and puts it in [changedBindings] with the [BindingLifecycleState.ADD] state.
+     * Adds a [ModuleBinding] to the registry, and puts it in [changedBindings] with the [BindingLifecycleState.ADD]
+     * state.
      *
      * @param binding the [ModuleBinding] to be put in the registry.
      */

diff --git a/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/ModelBinding.kt b/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/ModelBinding.kt
@@ -135,9 +135,9 @@ class ModelBinding(val model: SModelBase, branch: IBranch, serviceLocator: Servi
      *   3. the [model] is removed from the server or its files are deleted locally (or not),
      *   4. the [model] is removed from the [nodeMap].
      *
-     * After deactivation, the parameter 'callback' is run.
+     * After deactivation, the parameter [callback] is run.
      *
-     * @param removeFromServer if true, then the corresponding [module] will be removed from the model server.
+     * @param removeFromServer if true, then the corresponding [model] will be removed from the model server.
      * @param callback some action to run after the deactivation of the [ModelBinding].
      *
      * @return a [CompletableFuture] so caller of this method does not have to wait for the completion of the method.

diff --git a/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/ModuleBinding.kt b/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/bindings/ModuleBinding.kt
@@ -143,7 +143,7 @@ class ModuleBinding(val module: AbstractModule, branch: IBranch, serviceLocator:
      *   4. the [module] is removed from the server or its files are deleted locally (or not),
      *   5. the [module] is removed from the [nodeMap].
      *
-     *  After deactivation, the parameter 'callback' is run.
+     *  After deactivation, the parameter [callback] is run.
      *
      * @param removeFromServer if true, then the corresponding [module] will be removed from the model server.
      * @param callback some action to run after the deactivation of the [ModuleBinding].

diff --git a/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/modelix/branch/BranchRegistry.kt b/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/modelix/branch/BranchRegistry.kt
@@ -18,9 +18,12 @@ package org.modelix.mps.sync.modelix.branch
 
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.runBlocking
+import org.jetbrains.mps.openapi.model.SModel
+import org.jetbrains.mps.openapi.module.SModule
 import org.jetbrains.mps.openapi.module.SRepository
 import org.modelix.kotlin.utils.UnstableModelixFeature
 import org.modelix.model.api.IBranch
+import org.modelix.model.api.INode
 import org.modelix.model.client2.ModelClientV2
 import org.modelix.model.client2.ReplicatedModel
 import org.modelix.model.lazy.BranchReference
@@ -32,7 +35,7 @@ import org.modelix.mps.sync.mps.services.ServiceLocator
 
 /**
  * A registry to store the modelix [IBranch] we are connected to and the [ReplicatedModel] built from the content of it.
- * This can be used to access the most recent content of the branch as a tree of [org.modelix.model.api.INode]s.
+ * This can be used to access the most recent content of the branch as a tree of [INode]s.
  */
 @UnstableModelixFeature(
     reason = "The new modelix MPS plugin is under construction",
@@ -46,8 +49,7 @@ class BranchRegistry : InjectableService {
     private lateinit var serviceLocator: ServiceLocator
 
     /**
-     * The active [SRepository] to access the [org.jetbrains.mps.openapi.model.SModel]s and
-     * [org.jetbrains.mps.openapi.module.SModule]s in MPS.
+     * The active [SRepository] to access the [SModel]s and [SModule]s in MPS.
      */
     private val mpsRepository: SRepository
         get() = serviceLocator.mpsRepository
@@ -99,7 +101,7 @@ class BranchRegistry : InjectableService {
     }
 
     /**
-     * Connect to the branch identified by its [BranchReference] and return the branch's content as a [ReplicatedModel].
+     * Connect to the branch identified by [branchReference] and return the branch's content as a [ReplicatedModel].
      *
      * The branch's state depends on [ReplicatedModelInitContext.initialVersion] which tells the version of the branch
      * to use as a base. I.e. we assume that the modules and models running MPS are at
@@ -167,7 +169,7 @@ class BranchRegistry : InjectableService {
     }
 
     /**
-     * Registers a [ModelixBranchListener] to the branch with the [MPSLanguageRepository] as a language repository.
+     * Registers a [ModelixBranchListener] to the [branch] with the [languageRepository].
      *
      * @param branch the branch to which we register the [ModelixBranchListener] change listener.
      * @param languageRepository the [MPSLanguageRepository] to be used in the branch change listener.

diff --git a/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/modelix/tree/ITreeTraversal.kt b/mps-sync-plugin-lib/src/main/kotlin/org/modelix/mps/sync/modelix/tree/ITreeTraversal.kt
@@ -5,7 +5,12 @@ import kotlinx.coroutines.coroutineScope
 import kotlinx.coroutines.joinAll
 import kotlinx.coroutines.launch
 import org.modelix.kotlin.utils.UnstableModelixFeature
-import org.modelix.model.api.BuiltinLanguages
+import org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.DevkitDependency
+import org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.LanguageDependency
+import org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Model
+import org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.ModelReference
+import org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Module
+import org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.ModuleDependency
 import org.modelix.model.api.IBranch
 import org.modelix.model.api.INode
 import org.modelix.model.api.getRootNode
@@ -49,7 +54,7 @@ class ITreeTraversal(val branch: IBranch) {
     }
 
     /**
-     * Calls the [visitor] to visit each node in the [branch] starting from the parameter node until the last node in
+     * Calls the [visitor] to visit each node in the [branch] starting from the parameter [node] until the last node in
      * the tree.
      *
      * @param node the node to start visiting the tree from.
@@ -63,7 +68,7 @@ class ITreeTraversal(val branch: IBranch) {
             coroutineScope {
                 branch.runRead {
                     dependenciesJobs.addAll(
-                        node.getChildren(BuiltinLanguages.MPSRepositoryConcepts.Module.dependencies).map {
+                        node.getChildren(Module.dependencies).map {
                             launch {
                                 visitor.visitModuleDependency(node, it)
                             }
@@ -77,7 +82,7 @@ class ITreeTraversal(val branch: IBranch) {
             coroutineScope {
                 branch.runRead {
                     modelsJobs.addAll(
-                        node.getChildren(BuiltinLanguages.MPSRepositoryConcepts.Module.models).map {
+                        node.getChildren(Module.models).map {
                             launch {
                                 visit(it, visitor)
                             }
@@ -93,7 +98,7 @@ class ITreeTraversal(val branch: IBranch) {
             coroutineScope {
                 branch.runRead {
                     modelImportJobs.addAll(
-                        node.getChildren(BuiltinLanguages.MPSRepositoryConcepts.Model.modelImports).map {
+                        node.getChildren(Model.modelImports).map {
                             launch {
                                 visitor.visitModelImport(node, it)
                             }
@@ -107,7 +112,7 @@ class ITreeTraversal(val branch: IBranch) {
             coroutineScope {
                 branch.runRead {
                     usedLanguagesJobs.addAll(
-                        node.getChildren(BuiltinLanguages.MPSRepositoryConcepts.Model.usedLanguages).map {
+                        node.getChildren(Model.usedLanguages).map {
                             launch {
                                 if (it.isDevKitDependency()) {
                                     // visit devkit dependency
@@ -132,7 +137,7 @@ class ITreeTraversal(val branch: IBranch) {
             coroutineScope {
                 branch.runRead {
                     rootNodesJobs.addAll(
-                        node.getChildren(BuiltinLanguages.MPSRepositoryConcepts.Model.rootNodes).map {
+                        node.getChildren(Model.rootNodes).map {
                             launch {
                                 visit(it, visitor)
                             }
@@ -166,14 +171,14 @@ class ITreeTraversal(val branch: IBranch) {
  * */
 interface IBranchVisitor {
     /**
-     * Visits a [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Module] node.
+     * Visits a [Module] node.
      *
      * @param node the node to visit.
      */
     suspend fun visitModule(node: INode)
 
     /**
-     * Visits a [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Model] node.
+     * Visits a [Model] node.
      *
      * @param node the node to visit.
      */
@@ -187,40 +192,36 @@ interface IBranchVisitor {
     suspend fun visitNode(node: INode)
 
     /**
-     * Visits a [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.ModuleDependency] node.
+     * Visits a [ModuleDependency] node.
      *
-     * @param sourceModule the source [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Module] node from
-     * which the [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.ModuleDependency] originates.
+     * @param sourceModule the source [Module] node from which the [ModuleDependency] originates.
      *
      * @param moduleDependency the node to visit.
      */
     suspend fun visitModuleDependency(sourceModule: INode, moduleDependency: INode)
 
     /**
-     * Visits a [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.DevkitDependency] node.
+     * Visits a [DevkitDependency] node.
      *
-     * @param sourceModel the source [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Model] node from
-     * which the [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.DevkitDependency] originates.
+     * @param sourceModel the source [Model] node from which the [DevkitDependency] originates.
      *
      * @param devKitDependency the node to visit.
      */
     suspend fun visitDevKitDependency(sourceModel: INode, devKitDependency: INode)
 
     /**
-     * Visits a [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.LanguageDependency] node.
+     * Visits a [LanguageDependency] node.
      *
-     * @param sourceModel the source [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Model] node from
-     * which the [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.LanguageDependency] originates.
+     * @param sourceModel the source [Model] node from which the [LanguageDependency] originates.
      *
      * @param languageDependency the node to visit.
      */
     suspend fun visitLanguageDependency(sourceModel: INode, languageDependency: INode)
 
     /**
-     * Visits a [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.ModelReference] node.
+     * Visits a [ModelReference] node.
      *
-     * @param sourceModel the source [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.Model] node from
-     * which the [org.modelix.model.api.BuiltinLanguages.MPSRepositoryConcepts.ModelReference] originates.
+     * @param sourceModel the source [Model] node from which the [ModelReference] originates.
      *
      * @param modelImport the node to visit.
      */