Refactoring. API documentation.

5 files changed, 368 insertions, 51 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/form/select/AjaxOptions.kt b/src/main/kotlin/pl/treksoft/kvision/form/select/AjaxOptions.kt
index 774bb654..c026ccfd 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/select/AjaxOptions.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/select/AjaxOptions.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.form.select
 
 import pl.treksoft.jquery.JQueryXHR
@@ -5,12 +26,18 @@ import pl.treksoft.kvision.KVManager.AJAX_REQUEST_DELAY
 import pl.treksoft.kvision.KVManager.KVNULL
 import pl.treksoft.kvision.utils.obj
 
-enum class HttpType(val type: String) {
+/**
+ * HTTP protocol type for the AJAX call.
+ */
+enum class HTTPTYPE(internal val type: String) {
     GET("GET"),
     POST("POST")
 }
 
-enum class DataType(val type: String) {
+/**
+ * Data type for the AJAX call.
+ */
+enum class DATATYPE(internal val type: String) {
     JSON("json"),
     JSONP("jsonp"),
     XML("xml"),
@@ -18,18 +45,53 @@ enum class DataType(val type: String) {
     SCRIPT("script")
 }
 
+/**
+ * Data class for AJAX options.
+ *
+ * @constructor
+ * @param url the url address
+ * @param preprocessData
+ * [AjaxBootstrapSelect preprocessOption](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionspreprocessdata)
+ * option
+ * @param beforeSend
+ * [JQuery ajax.beforeSend](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) option
+ * @param data
+ * [JQuery ajax.data](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) option
+ * @param httpType
+ * [JQuery ajax.type](http://api.jquery.com/jquery.ajax/#jQuery-ajax-settings) option
+ * @param minLength
+ * [AjaxBootstrapSelect minLength](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionsminlength) option
+ * @param cache
+ * [AjaxBootstrapSelect cache](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionscache) option
+ * @param clearOnEmpty
+ * [AjaxBootstrapSelect clearOnEmpty](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionsclearonempty) option
+ * @param clearOnError
+ * [AjaxBootstrapSelect clearOnError](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionsclearonerror) option
+ * @param emptyRequest
+ * [AjaxBootstrapSelect emptyRequest](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionsemptyrequest) option
+ * @param requestDelay
+ * [AjaxBootstrapSelect requestDelay](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionsrequestdelay) option
+ * @param restoreOnError
+ * [AjaxBootstrapSelect restoreOnError](https://github.com/truckingsim/Ajax-Bootstrap-Select#optionsrestoreonerror)
+ * option
+ */
 data class AjaxOptions(
-    val url: String, val processData: (dynamic) -> dynamic, val beforeSend: ((JQueryXHR) -> dynamic)? = null,
-    val processParams: dynamic = null, val httpType: HttpType = HttpType.GET,
-    val dataType: DataType = DataType.JSON, val minLength: Int = 0,
+    val url: String, val preprocessData: (dynamic) -> dynamic, val beforeSend: ((JQueryXHR) -> dynamic)? = null,
+    val data: dynamic = null, val httpType: HTTPTYPE = HTTPTYPE.GET,
+    val dataType: DATATYPE = DATATYPE.JSON, val minLength: Int = 0,
     val cache: Boolean = true, val clearOnEmpty: Boolean = true, val clearOnError: Boolean = true,
     val emptyRequest: Boolean = false,
     val requestDelay: Int = AJAX_REQUEST_DELAY, val restoreOnError: Boolean = false
 )
 
+/**
+ * Convert AjaxOptions to JavaScript JSON object.
+ * @param emptyOption add an empty position as the first select option
+ * @return JSON object
+ */
 fun AjaxOptions.toJs(emptyOption: Boolean): dynamic {
     val procData = { data: dynamic ->
-        val processedData = this.processData(data)
+        val processedData = this.preprocessData(data)
         if (emptyOption) {
             val ret = mutableListOf(obj {
                 this.value = KVNULL
@@ -45,9 +107,9 @@ fun AjaxOptions.toJs(emptyOption: Boolean): dynamic {
     return obj {
         this.ajax = obj {
             this.url = url
-            this.type = httpType.type
+            this.type = HTTPTYPE.type
             this.dataType = dataType.type
-            this.data = processParams
+            this.data = data
             this.beforeSend = beforeSend
         }
         this.preprocessData = procData
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/select/Select.kt b/src/main/kotlin/pl/treksoft/kvision/form/select/Select.kt
index 49259ab1..e8494d58 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/select/Select.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/select/Select.kt
@@ -1,15 +1,50 @@
+/*
+ * 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.form.select
 
 import pl.treksoft.kvision.core.Component
+import pl.treksoft.kvision.core.StringBoolPair
+import pl.treksoft.kvision.core.StringPair
 import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.form.FieldLabel
 import pl.treksoft.kvision.form.HelpBlock
 import pl.treksoft.kvision.form.StringFormControl
 import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.utils.SnOn
-import pl.treksoft.kvision.core.StringBoolPair
-import pl.treksoft.kvision.core.StringPair
 
+/**
+ * The form field component for Select control.
+ *
+ * The select control can be populated directly from *options* parameter or manually by adding
+ * [SelectOption] or [SelectOptGroup] components to the container.
+ *
+ * @constructor
+ * @param options an optional list of options (label to value pairs) for the select control
+ * @param value selected value
+ * @param multiple allows multiple value selection (multiple values are comma delimited)
+ * @param ajaxOptions additional options for remote (AJAX) data source
+ * @param label label text bound to the input element
+ * @param rich determines if [label] can contain HTML code
+ */
 @Suppress("TooManyFunctions")
 open class Select(
     options: List<StringPair>? = null, value: String? = null,
@@ -17,66 +52,97 @@ open class Select(
     rich: Boolean = false
 ) : SimplePanel(setOf("form-group")), StringFormControl {
 
+    /**
+     * A list of options (label to value pairs) for the select control.
+     */
     var options
         get() = input.options
         set(value) {
             input.options = value
         }
+    /**
+     * A value of the selected option.
+     */
     override var value
         get() = input.value
         set(value) {
             input.value = value
         }
-    var startValue
-        get() = input.startValue
-        set(value) {
-            input.startValue = value
-        }
+    /**
+     * The name attribute of the generated HTML select element.
+     */
     var name
         get() = input.name
         set(value) {
             input.name = value
         }
+    /**
+     * Determines if multiple value selection is allowed.
+     */
     var multiple
         get() = input.multiple
         set(value) {
             input.multiple = value
         }
+    /**
+     * Additional options for remote (AJAX) data source.
+     */
     var ajaxOptions
         get() = input.ajaxOptions
         set(value) {
             input.ajaxOptions = value
         }
+    /**
+     * Maximal number of selected options.
+     */
     var maxOptions
         get() = input.maxOptions
         set(value) {
             input.maxOptions = value
         }
+    /**
+     * Determines if live search is available.
+     */
     var liveSearch
         get() = input.liveSearch
         set(value) {
             input.liveSearch = value
         }
+    /**
+     * The placeholder for the select control.
+     */
     var placeholder
         get() = input.placeholder
         set(value) {
             input.placeholder = value
         }
+    /**
+     * The style of the select control.
+     */
     var style
         get() = input.style
         set(value) {
             input.style = value
         }
+    /**
+     * The width of the select control.
+     */
     var selectWidth
         get() = input.selectWidth
         set(value) {
             input.selectWidth = value
         }
+    /**
+     * The width type of the select control.
+     */
     var selectWidthType
         get() = input.selectWidthType
         set(value) {
             input.selectWidthType = value
         }
+    /**
+     * Determines if an empty option is automatically generated.
+     */
     var emptyOption
         get() = input.emptyOption
         set(value) {
@@ -87,11 +153,25 @@ open class Select(
         set(value) {
             input.disabled = value
         }
+    /**
+     * Determines if the select is automatically focused.
+     */
+    var autofocus
+        get() = input.autofocus
+        set(value) {
+            input.autofocus = value
+        }
+    /**
+     * The label text bound to the select element.
+     */
     var label
         get() = flabel.text
         set(value) {
             flabel.text = value
         }
+    /**
+     * Determines if [label] can contain HTML code.
+     */
     var rich
         get() = flabel.rich
         set(value) {
@@ -121,7 +201,7 @@ open class Select(
     }
 
     companion object {
-        var counter = 0
+        internal var counter = 0
     }
 
     override fun getSnClass(): List<StringBoolPair> {
@@ -172,19 +252,24 @@ open class Select(
         return input.getChildren()
     }
 
+    /**
+     * Opens dropdown with options.
+     */
     open fun showOptions() {
         input.showOptions()
     }
 
+    /**
+     * Hides dropdown with options.
+     */
     open fun hideOptions() {
         input.hideOptions()
     }
 
+    /**
+     * Toggles visibility of dropdown with options.
+     */
     open fun toggleOptions() {
         input.toggleOptions()
     }
-
-    open fun deselect() {
-        input.deselect()
-    }
 }
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/select/SelectInput.kt b/src/main/kotlin/pl/treksoft/kvision/form/select/SelectInput.kt
index 83eca138..7374a30d 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/select/SelectInput.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/select/SelectInput.kt
@@ -1,22 +1,59 @@
+/*
+ * 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.form.select
 
 import com.github.snabbdom.VNode
+import pl.treksoft.kvision.KVManager.KVNULL
 import pl.treksoft.kvision.core.Component
 import pl.treksoft.kvision.core.CssSize
-import pl.treksoft.kvision.KVManager.KVNULL
+import pl.treksoft.kvision.core.StringBoolPair
+import pl.treksoft.kvision.core.StringPair
 import pl.treksoft.kvision.form.INPUTSIZE
 import pl.treksoft.kvision.html.BUTTONSTYLE
 import pl.treksoft.kvision.panel.SimplePanel
-import pl.treksoft.kvision.core.StringBoolPair
-import pl.treksoft.kvision.core.StringPair
-import pl.treksoft.kvision.utils.obj
 import pl.treksoft.kvision.utils.asString
+import pl.treksoft.kvision.utils.obj
 
-enum class SELECTWIDTHTYPE(val value: String) {
+/**
+ * Select width types. See [Bootstrap Select width](http://silviomoreto.github.io/bootstrap-select/examples/#width).
+ */
+enum class SELECTWIDTHTYPE(internal val value: String) {
     AUTO("auto"),
     FIT("fit")
 }
 
+/**
+ * The basic component for Select control.
+ *
+ * The select control can be populated directly from *options* parameter or manually by adding
+ * [SelectOption] or [SelectOptGroup] components to the container.
+ *
+ * @constructor
+ * @param options an optional list of options (label to value pairs) for the select control
+ * @param value selected value
+ * @param multiple allows multiple value selection (multiple values are comma delimited)
+ * @param ajaxOptions additional options for remote (AJAX) data source
+ * @param classes a set of CSS class names
+ */
 @Suppress("TooManyFunctions")
 open class SelectInput(
     options: List<StringPair>? = null, value: String? = null,
@@ -24,85 +61,122 @@ open class SelectInput(
     classes: Set<String> = setOf()
 ) : SimplePanel(classes) {
 
+    /**
+     * A list of options (label to value pairs) for the select control.
+     */
     internal var options = options
         set(value) {
             field = value
             setChildrenFromOptions()
         }
-
+    /**
+     * A value of the selected option.
+     */
     var value: String? = value
         set(value) {
             field = value
             refreshState()
         }
-
-    var startValue: String? = value
-        set(value) {
-            field = value
-            this.value = value
-            refresh()
-        }
+    /**
+     * The name attribute of the generated HTML select element.
+     */
     var name: String? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if multiple value selection is allowed.
+     */
     var multiple: Boolean = multiple
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Additional options for remote (AJAX) data source.
+     */
     var ajaxOptions: AjaxOptions? = ajaxOptions
         set(value) {
             field = value
             if (value != null) liveSearch = true
             refresh()
         }
+    /**
+     * Maximal number of selected options.
+     */
     var maxOptions: Int? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if live search is available.
+     */
     var liveSearch: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The placeholder for the select control.
+     */
     var placeholder: String? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The style of the select control.
+     */
     var style: BUTTONSTYLE? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The width of the select control.
+     */
     var selectWidth: CssSize? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The width type of the select control.
+     */
     var selectWidthType: SELECTWIDTHTYPE? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if an empty option is automatically generated.
+     */
     var emptyOption: Boolean = false
         set(value) {
             field = value
             setChildrenFromOptions()
         }
+    /**
+     * Determines if the field is disabled.
+     */
     var disabled: Boolean = false
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the select is automatically focused.
+     */
     var autofocus: Boolean? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * The size of the input.
+     */
     var size: INPUTSIZE? = null
         set(value) {
             field = value
@@ -141,7 +215,7 @@ open class SelectInput(
     }
 
     override fun render(): VNode {
-        return kvh("select", childrenVNodes())
+        return render("select", childrenVNodes())
     }
 
     override fun add(child: Component): SimplePanel {
@@ -184,22 +258,27 @@ open class SelectInput(
         this.refreshSelectInput()
     }
 
+    /**
+     * Opens dropdown with options.
+     */
     open fun showOptions() {
         getElementJQueryD()?.selectpicker("show")
     }
 
+    /**
+     * Hides dropdown with options.
+     */
     open fun hideOptions() {
         getElementJQueryD()?.selectpicker("hide")
     }
 
+    /**
+     * Toggles visibility of dropdown with options.
+     */
     open fun toggleOptions() {
         getElementJQueryD()?.selectpicker("toggle")
     }
 
-    open fun deselect() {
-        getElementJQueryD()?.selectpicker("deselectAll")
-    }
-
     override fun getSnClass(): List<StringBoolPair> {
         val cl = super.getSnClass().toMutableList()
         cl.add("selectpicker" to true)
@@ -209,7 +288,7 @@ open class SelectInput(
         return cl
     }
 
-    fun refreshSelectInput() {
+    private fun refreshSelectInput() {
         getElementJQueryD()?.selectpicker("refresh")
         refreshState()
     }
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOptGroup.kt b/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOptGroup.kt
index 391ee6a3..6819961f 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOptGroup.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOptGroup.kt
@@ -1,29 +1,74 @@
+/*
+ * 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.form.select
 
 import com.github.snabbdom.VNode
-import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.core.StringPair
+import pl.treksoft.kvision.panel.SimplePanel
 
+/**
+ * The helper container for adding option groups to [Select].
+ *
+ * The option group can be populated directly from *options* parameter or manually by adding
+ * [SelectOption] components to the container.
+ *
+ * @constructor
+ * @param label the label of the group
+ * @param options an optional list of options (label to value pairs) for the group
+ * @param maxOptions maximal number of selected options in the group
+ * @param disabled renders a disabled group
+ * @param classes a set of CSS class names
+ */
 open class SelectOptGroup(
     label: String, options: List<StringPair>? = null, maxOptions: Int? = null,
     disabled: Boolean = false, classes: Set<String> = setOf()
 ) : SimplePanel(classes) {
-
+    /**
+     * A label for the group.
+     */
     var label: String = label
         set(value) {
             field = value
             refresh()
         }
-    private var options = options
+    /**
+     * A list of options (label to value pairs) for the group.
+     */
+    var options = options
         set(value) {
             field = value
             setChildrenFromOptions()
         }
+    /**
+     * Maximal number of selected options in the group.
+     */
     var maxOptions: Int? = maxOptions
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the group is disabled.
+     */
     var disabled: Boolean = disabled
         set(value) {
             field = value
@@ -35,7 +80,7 @@ open class SelectOptGroup(
     }
 
     override fun render(): VNode {
-        return kvh("optgroup", childrenVNodes())
+        return render("optgroup", childrenVNodes())
     }
 
     private fun setChildrenFromOptions() {
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOption.kt b/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOption.kt
index f5ea25cd..e7a49120 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOption.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/select/SelectOption.kt
@@ -1,45 +1,91 @@
+/*
+ * 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.form.select
 
 import com.github.snabbdom.VNode
-import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.core.StringPair
+import pl.treksoft.kvision.core.Widget
 
+/**
+ * The helper component for adding options to [Select] or [SelectOptGroup].
+ *
+ * @constructor
+ * @param value the value of the option
+ * @param label the label of the option
+ * @param subtext the small subtext after the label of the option
+ * @param icon the icon before the label of the option
+ * @param divider renders this option as a divider
+ * @param disabled renders a disabled option
+ * @param classes a set of CSS class names
+ */
 open class SelectOption(
     value: String? = null, label: String? = null, subtext: String? = null, icon: String? = null,
     divider: Boolean = false, disabled: Boolean = false,
     classes: Set<String> = setOf()
 ) : Widget(classes) {
 
+    /**
+     * The value of the option.
+     */
     var value: String? = value
         set(value) {
             field = value
             refresh()
         }
-
+    /**
+     * The label of the option.
+     */
     var label: String? = label
         set(value) {
             field = value
             refresh()
         }
-
+    /**
+     * The subtext after the label of the option.
+     */
     var subtext: String? = subtext
         set(value) {
             field = value
             refresh()
         }
-
+    /**
+     * The icon before the label of the option.
+     */
     var icon: String? = icon
         set(value) {
             field = value
             refresh()
         }
-
+    /**
+     * Determines if the option should be rendered as divider.
+     */
     var divider: Boolean = divider
         set(value) {
             field = value
             refresh()
         }
-
+    /**
+     * Determines if the option should be disabled.
+     */
     var disabled: Boolean = disabled
         set(value) {
             field = value
@@ -48,9 +94,9 @@ open class SelectOption(
 
     override fun render(): VNode {
         return if (!divider) {
-            kvh("option", arrayOf(label ?: value))
+            render("option", arrayOf(label ?: value))
         } else {
-            kvh("option")
+            render("option")
         }
     }