Refactoring. API documentation.

67 files changed, 4025 insertions, 265 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/KVManager.kt b/src/main/kotlin/pl/treksoft/kvision/KVManager.kt
index 5d5c03fa..b60764df 100644
--- a/src/main/kotlin/pl/treksoft/kvision/KVManager.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/KVManager.kt
@@ -1,5 +1,23 @@
-/**
- * @author Robert Jaros
+/*
+ * 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
 
diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Component.kt b/src/main/kotlin/pl/treksoft/kvision/core/Component.kt
index c322892c..7125536a 100644
--- a/src/main/kotlin/pl/treksoft/kvision/core/Component.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/core/Component.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.core
 
 import com.github.snabbdom.VNode
@@ -5,20 +26,91 @@ import org.w3c.dom.Node
 import pl.treksoft.jquery.JQuery
 import pl.treksoft.kvision.panel.Root
 
+/**
+ * Base interface for all components.
+ */
 interface Component {
+    /**
+     * Parent of the current component.
+     */
     var parent: Component?
+    /**
+     * Visibility state of the current component.
+     */
     var visible: Boolean
 
-    fun addCssClass(css: String): Widget
-    fun removeCssClass(css: String): Widget
-    fun addSurroundingCssClass(css: String): Widget
-    fun removeSurroundingCssClass(css: String): Widget
+    /**
+     * Adds given value to the set of CSS classes generated in html code of current component.
+     * @param css CSS class name
+     * @return current component
+     */
+    fun addCssClass(css: String): Component
 
+    /**
+     * Removes given value from the set of CSS classes generated in html code of current component.
+     * @param css CSS class name
+     * @return current component
+     */
+    fun removeCssClass(css: String): Component
+
+    /**
+     * Adds given value to the set of CSS classes generated in html code of parent component.
+     * @param css CSS class name
+     * @return current component
+     */
+    fun addSurroundingCssClass(css: String): Component
+
+    /**
+     * Removes given value from the set of CSS classes generated in html code of parent component.
+     * @param css CSS class name
+     * @return current component
+     */
+    fun removeSurroundingCssClass(css: String): Component
+
+    /**
+     * @suppress
+     * Internal function
+     * Renders current component as a Snabbdom vnode.
+     * @return Snabbdom vnode
+     */
     fun renderVNode(): VNode
+
+    /**
+     * Returns DOM element bound to the current component.
+     * @return DOM element
+     */
     fun getElement(): Node?
+
+    /**
+     * Returns JQuery element bound to the current component.
+     * @return JQuery element
+     */
     fun getElementJQuery(): JQuery?
+
+    /**
+     * Returns JQuery element bound to the current component as a *dynamic* type.
+     * @return JQuery element as a *dynamic* type
+     */
     fun getElementJQueryD(): dynamic
+
+    /**
+     * @suppress
+     * Internal function.
+     * Sets **parent** property of current component to null.
+     * @return current component
+     */
     fun clearParent(): Component
+    /**
+     * @suppress
+     * Internal function.
+     * Returns root component - the root node of components tree
+     * @return root component
+     */
     fun getRoot(): Root?
+    /**
+     * @suppress
+     * Internal function
+     * Cleans resources allocated by the current component.
+     */
     fun dispose()
 }
diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Container.kt b/src/main/kotlin/pl/treksoft/kvision/core/Container.kt
index da436aba..a428ad14 100644
--- a/src/main/kotlin/pl/treksoft/kvision/core/Container.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/core/Container.kt
@@ -1,14 +1,60 @@
+/*
+ * 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.core
 
-import com.github.snabbdom.VNode
-
-interface Container {
-    var parent: Component?
-    var visible: Boolean
-    fun renderVNode(): VNode
+/**
+ * Base interface for all containers.
+ */
+interface Container : Component {
+    /**
+     * Adds given component to the current container.
+     * @param child child component
+     * @return current container
+     */
     fun add(child: Component): Container
+
+    /**
+     * Adds a list of components to the current container.
+     * @param children list of child components
+     * @return current container
+     */
     fun addAll(children: List<Component>): Container
+
+    /**
+     * Removes given component from the current container.
+     * @param child child component
+     * @return current container
+     */
     fun remove(child: Component): Container
+
+    /**
+     * Removes all children from the current container.
+     * @return current container
+     */
     fun removeAll(): Container
+
+    /**
+     * Returns a list of children of the current container.
+     * @return list of children
+     */
     fun getChildren(): List<Component>
 }
diff --git a/src/main/kotlin/pl/treksoft/kvision/core/Css.kt b/src/main/kotlin/pl/treksoft/kvision/core/Css.kt
index 80860647..8aeee71a 100644
--- a/src/main/kotlin/pl/treksoft/kvision/core/Css.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/core/Css.kt
@@ -1,10 +1,34 @@
+/*
+ * 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.core
 
 import pl.treksoft.kvision.utils.asString
 import pl.treksoft.kvision.utils.toHexString
 
+/**
+ * Definitions of CSS units.
+ */
 @Suppress("EnumNaming", "EnumEntryName")
-enum class UNIT(val unit: String) {
+enum class UNIT(internal val unit: String) {
     px("px"),
     pt("pt"),
     em("em"),
@@ -22,7 +46,10 @@ enum class UNIT(val unit: String) {
     auto("auto")
 }
 
-enum class BORDERSTYLE(val borderStyle: String) {
+/**
+ * Definitions of CSS border styles.
+ */
+enum class BORDERSTYLE(internal val borderStyle: String) {
     NONE("none"),
     HIDDEN("hidden"),
     DOTTED("dotted"),
@@ -37,7 +64,10 @@ enum class BORDERSTYLE(val borderStyle: String) {
     INHERIT("inherit")
 }
 
-enum class COLOR(val color: String) {
+/**
+ * Definitions of CSS color names.
+ */
+enum class COLOR(internal val color: String) {
     ALICEBLUE("aliceblue"),
     ANTIQUEWHITE("antiquewhite"),
     AQUA("aqua"),
@@ -181,63 +211,114 @@ enum class COLOR(val color: String) {
     YELLOWGREEN("yellowgreen")
 }
 
-enum class BGSIZE(val size: String) {
+/**
+ * Definitions of CSS background size.
+ */
+enum class BGSIZE(internal val size: String) {
     COVER("cover"),
     CONTAIN("contain")
 }
 
-enum class BGREPEAT(val repeat: String) {
+/**
+ * Definitions of CSS background repeat options.
+ */
+enum class BGREPEAT(internal val repeat: String) {
     REPEAT("repeat"),
     REPEATX("repeat-x"),
     REPEATY("repeat-y"),
     NOREPEAT("no-repeat")
 }
 
-enum class BGATTACH(val attachment: String) {
+/**
+ * Definitions of CSS background attachment options.
+ */
+enum class BGATTACH(internal val attachment: String) {
     SCROLL("scroll"),
     FIXED("fixed"),
     LOCAL("local")
 }
 
-enum class BGORIGIN(val origin: String) {
+/**
+ * Definitions of CSS background origin options.
+ */
+enum class BGORIGIN(internal val origin: String) {
     PADDING("padding-box"),
     BORDER("border-box"),
     CONTENT("content-box")
 }
 
-enum class BGCLIP(val clip: String) {
+/**
+ * Definitions of CSS background clipping options.
+ */
+enum class BGCLIP(internal val clip: String) {
     PADDING("padding-box"),
     BORDER("border-box"),
     CONTENT("content-box")
 }
 
+/**
+ * Type-safe definition of CSS border.
+ */
 class Border private constructor(
     private val width: CssSize? = null, private val style: BORDERSTYLE? = null,
     private val color: String? = null
 ) {
+    /**
+     * Creates CSS Border with given width and style.
+     * @param width width of the border
+     * @param style style of the border
+     */
     constructor(width: CssSize? = null, style: BORDERSTYLE? = null) : this(width, style, null)
+
+    /**
+     * Creates CSS Border with given width, style and color given in hex format.
+     * @param width width of the border
+     * @param style style of the border
+     * @param color color in hex format
+     */
     constructor(width: CssSize? = null, style: BORDERSTYLE? = null, color: Int) : this(
         width, style,
         "#" + color.toHexString()
     )
 
+    /**
+     * Creates CSS Border with given width, style and color given with named constant.
+     * @param width width of the border
+     * @param style style of the border
+     * @param color color named constant
+     */
     constructor(width: CssSize? = null, style: BORDERSTYLE? = null, color: COLOR) : this(width, style, color.color)
 
-    fun asString(): String {
+    internal fun asString(): String {
         val w = width?.asString()
         return w.orEmpty() + " " + (style?.borderStyle).orEmpty() + " " + color.orEmpty()
     }
 }
 
+/**
+ * Type-safe definition of CSS color.
+ */
 class Color private constructor(private val color: String? = null) {
+    /**
+     * Creates CSS Color with color given in hex format.
+     * @param color color in hex format
+     */
     constructor(color: Int) : this("#" + color.toHexString())
+
+    /**
+     * Creates CSS Color with color given with named constant.
+     * @param color color named constant
+     */
     constructor(color: COLOR) : this(color.color)
 
-    fun asString(): String {
+    internal fun asString(): String {
         return color.orEmpty()
     }
 }
 
+/**
+ * Type-safe definition of CSS background.
+ */
 class Background private constructor(
     private val color: String? = null, private val image: ResString? = null,
     private val positionX: CssSize? = null, private val positionY: CssSize? = null,
@@ -246,6 +327,19 @@ class Background private constructor(
     private val origin: BGORIGIN? = null, private val clip: BGCLIP? = null,
     private val attachment: BGATTACH? = null
 ) {
+    /**
+     * Creates CSS Background with given parameters.
+     * @param image background image
+     * @param positionX horizontal position of the background image
+     * @param positionY vertical position of the background image
+     * @param sizeX horizontal size of the background image
+     * @param sizeY vertical size of the background image
+     * @param size resize of the background image
+     * @param repeat repeat option of the background image
+     * @param origin origin option of the background image
+     * @param clip clipping option of the background image
+     * @param attachment attachment option of the background image
+     */
     constructor(
         image: ResString? = null, positionX: CssSize? = null, positionY: CssSize? = null,
         sizeX: CssSize? = null, sizeY: CssSize? = null, size: BGSIZE? = null,
@@ -256,6 +350,20 @@ class Background private constructor(
         image, positionX, positionY, sizeX, sizeY, size, repeat, origin, clip, attachment
     )
 
+    /**
+     * Creates CSS Background with given parameters.
+     * @param color color of the background in hex format
+     * @param image background image
+     * @param positionX horizontal position of the background image
+     * @param positionY vertical position of the background image
+     * @param sizeX horizontal size of the background image
+     * @param sizeY vertical size of the background image
+     * @param size resize of the background image
+     * @param repeat repeat option of the background image
+     * @param origin origin option of the background image
+     * @param clip clipping option of the background image
+     * @param attachment attachment option of the backgrou