Refactoring. API documentation.

3 files changed, 183 insertions, 0 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/utils/Keys.kt b/src/main/kotlin/pl/treksoft/kvision/utils/Keys.kt
new file mode 100644
index 00000000..d7e2927a
--- /dev/null
+++ b/src/main/kotlin/pl/treksoft/kvision/utils/Keys.kt
@@ -0,0 +1,31 @@
+/*
+ * 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.utils
+
+/**
+ * Keycode of the ENTER key.
+ */
+const val ENTER_KEY = 13
+/**
+ * Keycode of the ESC key.
+ */
+const val ESC_KEY = 27
diff --git a/src/main/kotlin/pl/treksoft/kvision/utils/Snabbdom.kt b/src/main/kotlin/pl/treksoft/kvision/utils/Snabbdom.kt
index 269fa6cb..e719d133 100644
--- a/src/main/kotlin/pl/treksoft/kvision/utils/Snabbdom.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/utils/Snabbdom.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.utils
 
 import com.github.snabbdom.Attrs
@@ -14,8 +35,14 @@ import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.StringPair
 import pl.treksoft.kvision.core.Widget
 
+/**
+ * JavaScript Object type
+ */
 external class Object
 
+/**
+ * Helper function for creating JavaScript objects.
+ */
 fun obj(init: dynamic.() -> Unit): dynamic {
     return (Object()).apply(init)
 }
@@ -23,15 +50,26 @@ fun obj(init: dynamic.() -> Unit): dynamic {
 @Suppress("UnsafeCastFromDynamic")
 private fun vNodeData(): VNodeData = js("({})")
 
+/**
+ * @suppress
+ * Internal interface.
+ */
 interface KvJQueryEventObject : JQueryEventObject {
     val clickedIndex: Int
 }
 
+/**
+ * Helper class for defining custom events.
+ */
 @Suppress("UnsafeCastFromDynamic")
 class KvEvent(type: String, eventInitDict: CustomEventInit) : CustomEvent(type, eventInitDict) {
     override val detail: KvJQueryEventObject = obj {}
 }
 
+/**
+ * @suppress
+ * Internal interface.
+ */
 interface BtOn : On {
     var showBsDropdown: ((KvEvent) -> kotlin.Unit)?
     var shownBsDropdown: ((KvEvent) -> kotlin.Unit)?
@@ -59,10 +97,17 @@ interface BtOn : On {
     var updateModel: ((KvEvent) -> kotlin.Unit)?
 }
 
+/**
+ * @suppress
+ * Internal interface.
+ */
 interface SnOn<T> : BtOn {
     var self: T
 }
 
+/**
+ * Helper function for creating object parameters for Snabbdom.
+ */
 fun snOpt(block: VNodeData.() -> Unit) = (vNodeData()::apply)(block)
 
 @Suppress("UnsafeCastFromDynamic")
@@ -77,6 +122,9 @@ internal fun hooks(): Hooks {
     return js("({})")
 }
 
+/**
+ * Helper function for creating style parameters for Snabbdom.
+ */
 @Suppress("UnsafeCastFromDynamic")
 fun snStyle(pairs: List<StringPair>): VNodeStyle {
     return obj {
@@ -84,6 +132,9 @@ fun snStyle(pairs: List<StringPair>): VNodeStyle {
     }
 }
 
+/**
+ * Helper function for creating properties parameters for Snabbdom.
+ */
 @Suppress("UnsafeCastFromDynamic")
 fun snProps(pairs: List<StringPair>): Props {
     return obj {
@@ -91,6 +142,9 @@ fun snProps(pairs: List<StringPair>): Props {
     }
 }
 
+/**
+ * Helper function for creating classes parameters for Snabbdom.
+ */
 @Suppress("UnsafeCastFromDynamic")
 fun snClasses(pairs: List<StringBoolPair>): Classes {
     return obj {
@@ -98,6 +152,9 @@ fun snClasses(pairs: List<StringBoolPair>): Classes {
     }
 }
 
+/**
+ * Helper function for creating attributes parameters for Snabbdom.
+ */
 @Suppress("UnsafeCastFromDynamic")
 fun snAttrs(pairs: List<StringPair>): Attrs {
     return obj {
diff --git a/src/main/kotlin/pl/treksoft/kvision/utils/Utils.kt b/src/main/kotlin/pl/treksoft/kvision/utils/Utils.kt
index 7ba01135..36aae88d 100644
--- a/src/main/kotlin/pl/treksoft/kvision/utils/Utils.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/utils/Utils.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.
+ */
 @file:Suppress("TooManyFunctions")
 
 package pl.treksoft.kvision.utils
@@ -7,24 +28,85 @@ import pl.treksoft.kvision.core.CssSize
 import pl.treksoft.kvision.core.UNIT
 import kotlin.js.Date
 
+/**
+ * Extension function to convert Int to CSS px units.
+ */
 fun Int.px(): CssSize = Pair(this, UNIT.px)
+
+/**
+ * Extension function to convert Int to CSS em units.
+ */
 fun Int.em(): CssSize = Pair(this, UNIT.em)
+
+/**
+ * Extension function to convert Int to CSS pt units.
+ */
 fun Int.pt(): CssSize = Pair(this, UNIT.pt)
+
+/**
+ * Extension function to convert Int to CSS percent units.
+ */
 fun Int.perc(): CssSize = Pair(this, UNIT.perc)
+
+/**
+ * Extension function to convert Int to CSS rem units.
+ */
 fun Int.rem(): CssSize = Pair(this, UNIT.rem)
+
+/**
+ * Extension function to convert Int to CSS ch units.
+ */
 fun Int.ch(): CssSize = Pair(this, UNIT.ch)
+
+/**
+ * Extension function to convert Int to CSS cm units.
+ */
 fun Int.cm(): CssSize = Pair(this, UNIT.cm)
+
+/**
+ * Extension function to convert Int to CSS mm units.
+ */
 fun Int.mm(): CssSize = Pair(this, UNIT.mm)
+
+/**
+ * Extension function to convert Int to CSS in units.
+ */
 @Suppress("FunctionNaming")
 fun Int.`in`(): CssSize = Pair(this, UNIT.`in`)
 
+/**
+ * Extension function to convert Int to CSS pc units.
+ */
 fun Int.pc(): CssSize = Pair(this, UNIT.pc)
+
+/**
+ * Extension function to convert Int to CSS vh units.
+ */
 fun Int.vh(): CssSize = Pair(this, UNIT.vh)
+
+/**
+ * Extension function to convert Int to CSS vw units.
+ */
 fun Int.vw(): CssSize = Pair(this, UNIT.vw)
+
+/**
+ * Extension function to convert Int to CSS vmin units.
+ */
 fun Int.vmin(): CssSize = Pair(this, UNIT.vmin)
+
+/**
+ * Extension function to convert Int to CSS vmax units.
+ */
 fun Int.vmax(): CssSize = Pair(this, UNIT.vmax)
+
+/**
+ * Helper function to describe CSS auto value.
+ */
 fun auto(): CssSize = Pair(0, UNIT.auto)
 
+/**
+ * Extension function to convert CssSize to String.
+ */
 fun CssSize.asString(): String {
     return if (this.second != UNIT.auto) {
         this.first.toString() + this.second.unit
@@ -35,6 +117,9 @@ fun CssSize.asString(): String {
 
 private val hex = arrayOf("0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "a", "b", "c", "d", "e", "f")
 
+/**
+ * Extension function to convert Int to hex format.
+ */
 @Suppress("MagicNumber")
 fun Int.toHexString(): String {
     var result = ""
@@ -46,11 +131,21 @@ fun Int.toHexString(): String {
     return result
 }
 
+/**
+ * Extension function to convert String to Date with a given date format.
+ * @param format date/time format
+ * @return Date object
+ */
 @Suppress("UnsafeCastFromDynamic")
 fun String.toDateF(format: String = "YYYY-MM-DD HH:mm:ss"): Date {
     return KVManager.fecha.parse(this, format)
 }
 
+/**
+ * Extension function to convert Date to String with a given date format.
+ * @param format date/time format
+ * @return String object
+ */
 @Suppress("UnsafeCastFromDynamic")
 fun Date.toStringF(format: String = "YYYY-MM-DD HH:mm:ss"): String {
     return KVManager.fecha.format(this, format)