Refactoring. API documentation.

3 files changed, 105 insertions, 5 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/data/DataComponent.kt b/src/main/kotlin/pl/treksoft/kvision/data/DataComponent.kt
index 6eef6f98..4e5b92d5 100644
--- a/src/main/kotlin/pl/treksoft/kvision/data/DataComponent.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/data/DataComponent.kt
@@ -1,12 +1,44 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.data
 
 import kotlin.properties.ObservableProperty
 import kotlin.properties.ReadWriteProperty
 import kotlin.reflect.KProperty
 
+/**
+ * Base interface for observable data model.
+ */
 interface DataComponent {
+    /**
+     * @suppress
+     * Internal property
+     */
     var container: DataUpdatable?
 
+    /**
+     * @suppress
+     * Internal function for observable properties
+     */
     fun <T> obs(initialValue: T): ReadWriteProperty<Any?, T> = object : ObservableProperty<T>(initialValue) {
         override fun afterChange(property: KProperty<*>, oldValue: T, newValue: T) {
             container?.update()
@@ -14,6 +46,9 @@ interface DataComponent {
     }
 }
 
-open class BaseDataComponent : DataComponent {
+/**
+ * Base abstract class for creating observable data model.
+ */
+abstract class BaseDataComponent : DataComponent {
     override var container: DataUpdatable? = null
 }
diff --git a/src/main/kotlin/pl/treksoft/kvision/data/DataContainer.kt b/src/main/kotlin/pl/treksoft/kvision/data/DataContainer.kt
index af53807c..209c9ae6 100644
--- a/src/main/kotlin/pl/treksoft/kvision/data/DataContainer.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/data/DataContainer.kt
@@ -1,3 +1,24 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.data
 
 import com.github.snabbdom.VNode
@@ -7,8 +28,18 @@ import pl.treksoft.kvision.core.Container
 import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.panel.VPanel
 
-class DataContainer<M : DataComponent, C : Widget>(
-    val model: ObservableList<M>,
+/**
+ * A container class with support for observable data model.
+ *
+ * @constructor Creates DataContainer bound to given data model.
+ * @param M base data model type
+ * @param C base component type
+ * @param model data model of type *ObservableList<M>*
+ * @param binding a function which creates component C from data model at given index
+ * @param child internal container (defaults to [VPanel])
+ */
+class DataContainer<M : DataComponent, C : Component>(
+    private val model: ObservableList<M>,
     private val binding: (Int) -> C,
     private val child: Container = VPanel()
 ) :
@@ -58,8 +89,9 @@ class DataContainer<M : DataComponent, C : Widget>(
         return this.child.renderVNode()
     }
 
-    fun get(index: Int): M = model[index]
-
+    /**
+     * Updates view from the current data model state.
+     */
     override fun update() {
         model.forEach { it.container = this }
         singleRender {
@@ -69,11 +101,20 @@ class DataContainer<M : DataComponent, C : Widget>(
         onUpdateHandler?.invoke()
     }
 
+    /**
+     * Sets a notification handler called after every update.
+     * @param handler notification handler
+     * @return current container
+     */
     fun onUpdate(handler: () -> Unit): DataContainer<M, C> {
         onUpdateHandler = handler
         return this
     }
 
+    /**
+     * Clears notification handler.
+     * @return current container
+     */
     fun clearOnUpdate(): DataContainer<M, C> {
         onUpdateHandler = null
         return this
diff --git a/src/main/kotlin/pl/treksoft/kvision/data/DataUpdatable.kt b/src/main/kotlin/pl/treksoft/kvision/data/DataUpdatable.kt
index 5f9b7563..7c54e864 100644
--- a/src/main/kotlin/pl/treksoft/kvision/data/DataUpdatable.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/data/DataUpdatable.kt
@@ -1,5 +1,29 @@
+/*
+ * Copyright (c) 2017-present Robert Jaros
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
 package pl.treksoft.kvision.data
 
+/**
+ * Interface for updatable container.
+ */
 interface DataUpdatable {
     fun update()
 }