Merge pull request #94 from modelix/docs/model-api

MODELIX-419 Add documentation for model api reference

Author: mhuster23

model-api/src/commonMain/kotlin/org/modelix/model/api/ConceptUtil.kt

@@ -13,6 +13,11 @@
  */
 package org.modelix.model.api
 
+/**
+ * Returns this concept and all of its super-concepts.
+ *
+ * @return list of this concept and all its super-concepts
+ */
 fun IConcept.getAllConcepts(): List<IConcept> {
     val acc = LinkedHashSet<IConcept>()
     collectConcepts(this, acc)

model-api/src/commonMain/kotlin/org/modelix/model/api/IBranch.kt

@@ -15,35 +15,140 @@
 
 package org.modelix.model.api
 
+/**
+ * Representation of a branch.
+ */
 interface IBranch {
+    /**
+     * Returns the id of this branch.
+     *
+     * @return branch id
+     */
     fun getId(): String
+
+    /**
+     * Performs a read operation on this branch.
+     *
+     * @param runnable read operation to be performed
+     */
     fun runRead(runnable: () -> Unit)
+
+    /**
+     * Performs a function in a read transaction on this branch.
+     *
+     * @param f function to be performed
+     */
     fun runReadT(f: (IReadTransaction) -> Unit) {
         runRead { f(readTransaction) }
     }
+
+    /**
+     * Performs a computable read operation, which returns a value, on this branch.
+     *
+     * @param computable operation to be performed
+     */
     fun <T> computeRead(computable: () -> T): T
+
+    /**
+     * Performs a computable read operation, which returns a value, in a read transaction on this branch.
+     */
     fun <T> computeReadT(computable: (IReadTransaction) -> T): T {
         return computeRead { computable(readTransaction) }
     }
+
+    /**
+     * Performs a write operation on this branch.
+     *
+     * @param runnable operation to be performed
+     */
     fun runWrite(runnable: () -> Unit)
+
+    /**
+     * Performs a function in a write transaction on this branch.
+     *
+     * @param f function to be performed
+     */
     fun runWriteT(f: (IWriteTransaction) -> Unit) {
         runWrite { f(writeTransaction) }
     }
+
+    /**
+     * Performs a computable write operation, which returns a value, on this branch.
+     *
+     * @param computable operation to be performed
+     */
     fun <T> computeWrite(computable: () -> T): T
+
+    /**
+     * Performs a computable write operation, which returns a value, in a write transaction on this branch.
+     */
     fun <T> computeWriteT(computable: (IWriteTransaction) -> T): T {
         return computeWrite { computable(writeTransaction) }
     }
+
+    /**
+     * Checks if read operations can be performed on this branch.
+     *
+     * @return true if read operations can be performed, false otherwise
+     */
     fun canRead(): Boolean
+
+    /**
+     * Checks if write operations can be performed on this branch.
+     *
+     * @return true if write operations can be performed, false otherwise
+     */
     fun canWrite(): Boolean
+
+    /**
+     * Transaction for this branch.
+     */
     val transaction: ITransaction
+
+    /**
+     * Read transaction for this branch.
+     */
     val readTransaction: IReadTransaction
+
+    /**
+     * Write transaction for this branch.
+     */
     val writeTransaction: IWriteTransaction
+
+    /**
+     * Adds the given branch listener to this branch.
+     *
+     * The branch listener will listen to changes on this branch.
+     *
+     * @param l branch listener to be added
+     */
     fun addListener(l: IBranchListener)
+
+    /**
+     * Removes the given branch listener from this branch.
+     *
+     * @param l branch listener to be removed
+     */
     fun removeListener(l: IBranchListener)
 }
 
+/**
+ * Wrapper for [IBranch]
+ */
 interface IBranchWrapper : IBranch {
+    /**
+     * Unwraps the branch.
+     *
+     * @return unwrapped branch
+     */
     fun unwrapBranch(): IBranch
 }
 
+/**
+ * Recursively unwraps a branch.
+ *
+ * If the receiver is an [IBranchWrapper] it will be unwrapped else the branch will be returned.
+ *
+ * @return deep unwrapped branch
+ */
 fun IBranch.deepUnwrap(): IBranch = if (this is IBranchWrapper) unwrapBranch().deepUnwrap() else this

model-api/src/commonMain/kotlin/org/modelix/model/api/IBranchListener.kt

@@ -15,6 +15,15 @@
 
 package org.modelix.model.api
 
+/**
+ * Listener, that listens for changes on a branch.
+ */
 interface IBranchListener {
+    /**
+     * Informs the branch listener about tree changes.
+     *
+     * @param oldTree the original tree state
+     * @param newTree the new tree state
+     */
     fun treeChanged(oldTree: ITree?, newTree: ITree)
 }

model-api/src/commonMain/kotlin/org/modelix/model/api/IChildLink.kt

@@ -15,7 +15,13 @@
 
 package org.modelix.model.api
 
+/**
+ * Representation of a parent-child relationship between [IConcept]s.
+ */
 interface IChildLink : ILink {
+    /**
+     * Specifies if the parent-child relation ship is 1:n.
+     */
     val isMultiple: Boolean
 
     @Deprecated("use .targetConcept")

model-api/src/commonMain/kotlin/org/modelix/model/api/IConcept.kt

@@ -15,30 +15,162 @@
 
 package org.modelix.model.api
 
+/**
+ * Representation of a language concept.
+ */
 interface IConcept {
+
+    /**
+     * Returns a reference to this concept.
+     *
+     * @return concept reference
+     */
     fun getReference(): IConceptReference
+
+    /**
+     * The language this concept is part of.
+     */
     val language: ILanguage?
 
+    /**
+     * Returns unique concept id of this concept.
+     *
+     * @return unique concept id
+     */
     fun getUID(): String
+
+    /**
+     * Returns the name of this concept.
+     *
+     * @return short concept name
+     */
     fun getShortName(): String
+
+    /**
+     * Returns the name of this concept prefixed by the language name.
+     *
+     * @return long concept name
+     */
     fun getLongName(): String
+
+    /**
+     * Checks if this concept is abstract.
+     *
+     * @return true if the concept is abstract, false otherwise
+     */
     fun isAbstract(): Boolean
 
+    /**
+     * Checks if this concept is a sub-concept of the given concept.
+     *
+     * @param superConcept the potential super-concept
+     * @return true if the given concept is a super-concept of this concept, false otherwise
+     */
     fun isSubConceptOf(superConcept: IConcept?): Boolean
+
+    /**
+     * Returns the direct super concepts of this concept.
+     *
+     * @return list of direct super concepts
+     */
     fun getDirectSuperConcepts(): List<IConcept>
+
+    /**
+     * Checks if the given concept is equal to this concept.
+     *
+     * @return true if this concept is equal to the given concept, false otherwise
+     */
     fun isExactly(concept: IConcept?): Boolean
 
+    /**
+     * Returns the properties, which are directly defined in this concept.
+     *
+     * @return list of own properties
+     *
+     * @see getAllProperties
+     */
     fun getOwnProperties(): List<IProperty>
+
+    /**
+     * Returns the child links, which are directly defined in this concept.
+     *
+     * @return list of own child links
+     *
+     * @see getAllChildLinks
+     */
     fun getOwnChildLinks(): List<IChildLink>
+
+    /**
+     * Returns the reference links, which are directly defined in this concept.
+     *
+     * @return list of reference links
+     *
+     * @see getAllChildLinks
+     */
     fun getOwnReferenceLinks(): List<IReferenceLink>
 
+    /**
+     * Returns all properties of this concept.
+     *
+     * This includes properties, that are directly defined in the concept itself,
+     * and properties, which are defined in the super-concepts of this concept.
+     *
+     * @return list of all properties
+     *
+     * @see getOwnProperties
+     */
     fun getAllProperties(): List<IProperty>
+
+    /**
+     * Returns all child links of this concept.
+     *
+     * This includes child links, that are directly defined in the concept itself,
+     * and child links, which are defined in the super-concepts of this concept.
+     *
+     * @return list of all child links
+     *
+     * @see getOwnChildLinks
+     */
     fun getAllChildLinks(): List<IChildLink>
+
+    /**
+     * Returns all reference links of this concepts.
+     *
+     * This includes reference links, that are directly defined in the concept itself,
+     * and reference links, which are defined in the super-concepts of this concept.
+     *
+     * @return list of all reference links
+     *
+     * @see getOwnReferenceLinks
+     */
     fun getAllReferenceLinks(): List<IReferenceLink>
 
+    /**
+     * Returns the property with the given name.
+     *
+     * @param name name of the property
+     * @return property
+     */
     fun getProperty(name: String): IProperty
+
+    /**
+     * Returns the child link with the given name.
+     *
+     * @param name name of the child link
+     * @return child link
+     */
     fun getChildLink(name: String): IChildLink
+
+    /**
+     * Returns the reference link with the given name.
+     *
+     * @param name name of the reference link
+     * @return reference link
+     */
     fun getReferenceLink(name: String): IReferenceLink
 }
 
+/**
+ * @see IConcept.isSubConceptOf
+ */
 fun IConcept?.isSubConceptOf(superConcept: IConcept?) = this?.isSubConceptOf(superConcept) == true

model-api/src/commonMain/kotlin/org/modelix/model/api/IConceptReference.kt

@@ -15,6 +15,9 @@ package org.modelix.model.api
 
 import org.modelix.model.area.IArea
 
+/**
+ * Reference to an [IConcept].
+ */
 interface IConceptReference {
     companion object {
         private var deserializers: Map<Any, ((String) -> IConceptReference?)> = LinkedHashMap()
@@ -41,6 +44,11 @@ interface IConceptReference {
         }
     }
 
+    /**
+     * Returns the unique id of this concept reference.
+     *
+     * @return uid of this concept reference
+     */
     fun getUID(): String
 
     @Deprecated("use ILanguageRepository.resolveConcept")
@@ -50,5 +58,25 @@ interface IConceptReference {
     fun serialize(): String
 }
 
+/**
+ * Resolves the receiver concept reference within all registered language repositories.
+ *
+ * @receiver concept reference to be resolved
+ * @return resolved concept
+ * @throws RuntimeException if the concept could not be found
+ *          or multiple concepts were found for this concept reference
+ *
+ * @see ILanguageRepository.resolveConcept
+ */
 fun IConceptReference.resolve(): IConcept = ILanguageRepository.resolveConcept(this)
+
+/**
+ * Tries to resolve the receiver concept reference within all registered language repositories.
+ *
+ * @receiver concept reference to be resolved
+ * @return resolved concept or null, if the concept could not be found
+ * @throws RuntimeException if multiple concepts were found for this concept reference
+ *
+ * @see ILanguageRepository.tryResolveConcept
+ */
 fun IConceptReference.tryResolve(): IConcept? = ILanguageRepository.tryResolveConcept(this)