Refactoring. API documentation.

27 files changed, 1767 insertions, 115 deletions

diff --git a/src/main/kotlin/pl/treksoft/kvision/form/FieldLabel.kt b/src/main/kotlin/pl/treksoft/kvision/form/FieldLabel.kt
index 81275070..b4be8f8e 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/FieldLabel.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/FieldLabel.kt
@@ -1,9 +1,39 @@
+/*
+ * 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
 
+import pl.treksoft.kvision.core.StringPair
 import pl.treksoft.kvision.html.TAG
 import pl.treksoft.kvision.html.Tag
-import pl.treksoft.kvision.core.StringPair
 
+/**
+ * Helper class for HTML label element.
+ *
+ * @constructor
+ * @param forId the value of *for* attribute
+ * @param text the text of the label
+ * @param rich determines if [text] can contain HTML code
+ * @param classes a set of CSS class names
+ */
 open class FieldLabel(
     internal val forId: String, text: String? = null, rich: Boolean = false,
     classes: Set<String> = setOf("control-label")
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/Form.kt b/src/main/kotlin/pl/treksoft/kvision/form/Form.kt
index 1f97311d..e91002e9 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/Form.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/Form.kt
@@ -1,22 +1,63 @@
+/*
+ * 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
 
 import kotlin.js.Date
 import kotlin.js.Json
 
-data class FieldParams<in F : FormControl>(
+/**
+ * Internal data class containing form field parameters.
+ */
+internal data class FieldParams<in F : FormControl>(
     val required: Boolean = false,
     val validatorMessage: ((F) -> String?)? = null,
     val validator: ((F) -> Boolean?)? = null
 )
 
-open class Form<K>(private val panel: FormPanel<K>? = null, private val modelFactory: (Map<String, Any?>) -> K) {
+/**
+ * The form definition class. Can be used directly or indirectly inside a [FormPanel].
+ *
+ * @constructor Creates a form with a given modelFactory function
+ * @param K model class type
+ * @param panel optional instance of [FormPanel]
+ * @param modelFactory function transforming a Map<String, Any?> to a data model of class K
+ */
+class Form<K>(private val panel: FormPanel<K>? = null, private val modelFactory: (Map<String, Any?>) -> K) {
 
     internal val fields: MutableMap<String, FormControl> = mutableMapOf()
     internal val fieldsParams: MutableMap<String, Any> = mutableMapOf()
     internal var validatorMessage: ((Form<K>) -> String?)? = null
     internal var validator: ((Form<K>) -> Boolean?)? = null
 
-    open fun <C : FormControl> add(
+    /**
+     * Adds a control to the form.
+     * @param key key identifier of the control
+     * @param control the form control
+     * @param required determines if the control is required
+     * @param validatorMessage optional function returning validation message
+     * @param validator optional validation function
+     * @return current form
+     */
+    fun <C : FormControl> add(
         key: String, control: C, required: Boolean = false,
         validatorMessage: ((C) -> String?)? = null,
         validator: ((C) -> Boolean?)? = null
@@ -26,53 +67,91 @@ open class Form<K>(private val panel: FormPanel<K>? = null, private val modelFac
         return this
     }
 
-    open fun remove(key: String): Form<K> {
+    /**
+     * Removes a control from the form.
+     * @param key key identifier of the control
+     * @return current form
+     */
+    fun remove(key: String): Form<K> {
         this.fields.remove(key)
         return this
     }
 
-    open fun removeAll(): Form<K> {
+    /**
+     * Removes all controls from the form.
+     * @return current form
+     */
+    fun removeAll(): Form<K> {
         this.fields.clear()
         return this
     }
 
-    open fun getControl(key: String): FormControl? {
+    /**
+     * Returns a control of given key.
+     * @param key key identifier of the control
+     * @return selected control
+     */
+    fun getControl(key: String): FormControl? {
         return this.fields[key]
     }
 
+    /**
+     * Returns a value of the control of given key.
+     * @param key key identifier of the control
+     * @return value of the control
+     */
     operator fun get(key: String): Any? {
         return getControl(key)?.getValue()
     }
 
-    open fun setData(data: K) {
+    /**
+     * Sets the values of all the controls from the model.
+     * @param model data model
+     */
+    fun setData(model: K) {
         fields.forEach { it.value.setValue(null) }
-        val map = data.asDynamic().map as? Map<String, Any?>
+        val map = model.asDynamic().map as? Map<String, Any?>
         if (map != null) {
             map.forEach {
                 fields[it.key]?.setValue(it.value)
             }
         } else {
-            for (key in js("Object").keys(data)) {
+            for (key in js("Object").keys(model)) {
                 @Suppress("UnsafeCastFromDynamic")
-                fields[key]?.setValue(data.asDynamic()[key])
+                fields[key]?.setValue(model.asDynamic()[key])
             }
         }
     }
 
-    open fun clearData() {
+    /**
+     * Sets the values of all controls to null.
+     */
+    fun clearData() {
         fields.forEach { it.value.setValue(null) }
     }
 
-    open fun getData(): K {
+    /**
+     * Returns current data model.
+     * @return data model
+     */
+    fun getData(): K {
         val map = fields.entries.associateBy({ it.key }, { it.value.getValue() })
         return modelFactory(map.withDefault { null })
     }
 
-    open fun getDataJson(): Json {
+    /**
+     * Returns current data model as JSON.
+     * @return data model as JSON
+     */
+    fun getDataJson(): Json {
         return fields.entries.associateBy({ it.key }, { it.value.getValue() }).asJson()
     }
 
-    open fun validate(): Boolean {
+    /**
+     * Invokes validator function and validates the form.
+     * @return validation result
+     */
+    fun validate(): Boolean {
         val fieldWithError = fieldsParams.mapNotNull { entry ->
             fields[entry.key]?.let { control ->
                 @Suppress("UNCHECKED_CAST")
@@ -95,7 +174,7 @@ open class Form<K>(private val panel: FormPanel<K>? = null, private val modelFac
         }.find { it }
         val validatorPassed = validator?.invoke(this) ?: true
         panel?.validatorError = if (!validatorPassed) {
-            panel?.validatorMessage?.invoke(this) ?: "Invalid form data"
+            validatorMessage?.invoke(this) ?: "Invalid form data"
         } else {
             null
         }
@@ -103,11 +182,29 @@ open class Form<K>(private val panel: FormPanel<K>? = null, private val modelFac
     }
 }
 
+/**
+ * Returns given value from the map as a String.
+ */
 fun Map<String, Any?>.string(key: String): String? = this[key] as? String
+
+/**
+ * Returns given value from the map as a Number.
+ */
 fun Map<String, Any?>.number(key: String): Number? = this[key] as? Number
+
+/**
+ * Returns given value from the map as a Boolean.
+ */
 fun Map<String, Any?>.bool(key: String): Boolean? = this[key] as? Boolean
+
+/**
+ * Returns given value from the map as a Date.
+ */
 fun Map<String, Any?>.date(key: String): Date? = this[key] as? Date
 
+/**
+ * Returns map values in JSON format.
+ */
 fun Map<String, Any?>.asJson(): Json {
     val array = this.entries.map { it.component1() to it.component2() }.toTypedArray()
     @Suppress("SpreadOperator")
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/FormControl.kt b/src/main/kotlin/pl/treksoft/kvision/form/FormControl.kt
index d0858d4e..b8e9a1b4 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/FormControl.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/FormControl.kt
@@ -1,23 +1,90 @@
+/*
+ * 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
 
 import pl.treksoft.kvision.core.Component
 import kotlin.js.Date
 
+/**
+ * Input controls sizes.
+ */
 enum class INPUTSIZE(val className: String) {
     LARGE("input-lg"),
     SMALL("input-sm")
 }
 
+/**
+ * Base interface of a form control.
+ */
 interface FormControl : Component {
+    /**
+     * Determines if the field is disabled.
+     */
     var disabled: Boolean
+    /**
+     * Input control size.
+     */
     var size: INPUTSIZE?
+    /**
+     * The actual input component.
+     */
     val input: Component
+    /**
+     * Form field label.
+     */
     val flabel: FieldLabel
+    /**
+     * Validation info component.
+     */
     val validationInfo: HelpBlock
+
+    /**
+     * Returns the value of the control.
+     * @return the value
+     */
     fun getValue(): Any?
+
+    /**
+     * Sets the value of the control.
+     * @param v the value
+     */
     fun setValue(v: Any?)
+
+    /**
+     * Returns the value of the control as a String.
+     */
     fun getValueAsString(): String?
+
+    /**
+     * @suppress
+     * Internal function
+     * Re-renders the current component.
+     * @return current component
+     */
     fun refresh(): Component
+
+    /**
+     * Validator error message.
+     */
     var validatorError: String?
         get() = validationInfo.text
         set(value) {
@@ -27,8 +94,15 @@ interface FormControl : Component {
         }
 }
 
+/**
+ * Base interface of a form control with a text value.
+ */
 interface StringFormControl : FormControl {
+    /**
+     * Text value.
+     */
     var value: String?
+
     override fun getValue(): String? = value
     override fun setValue(v: Any?) {
         value = v as? String
@@ -37,8 +111,15 @@ interface StringFormControl : FormControl {
     override fun getValueAsString(): String? = value
 }
 
+/**
+ * Base interface of a form control with a numeric value.
+ */
 interface NumberFormControl : FormControl {
+    /**
+     * Numeric value.
+     */
     var value: Number?
+
     override fun getValue(): Number? = value
     override fun setValue(v: Any?) {
         value = v as? Number
@@ -47,8 +128,15 @@ interface NumberFormControl : FormControl {
     override fun getValueAsString(): String? = value?.toString()
 }
 
+/**
+ * Base interface of a form control with a boolean value.
+ */
 interface BoolFormControl : FormControl {
+    /**
+     * Boolean value.
+     */
     var value: Boolean
+
     override fun getValue(): Boolean = value
     override fun setValue(v: Any?) {
         value = v as? Boolean ?: false
@@ -57,8 +145,15 @@ interface BoolFormControl : FormControl {
     override fun getValueAsString(): String? = value.toString()
 }
 
+/**
+ * Base interface of a form control with a date value.
+ */
 interface DateFormControl : FormControl {
+    /**
+     * Date value.
+     */
     var value: Date?
+
     override fun getValue(): Date? = value
     override fun setValue(v: Any?) {
         value = v as? Date
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/FormPanel.kt b/src/main/kotlin/pl/treksoft/kvision/form/FormPanel.kt
index 4ab94df5..0a12f818 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/FormPanel.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/FormPanel.kt
@@ -1,29 +1,68 @@
+/*
+ * 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
 
 import com.github.snabbdom.VNode
+import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.form.check.CheckBox
 import pl.treksoft.kvision.form.check.Radio
 import pl.treksoft.kvision.html.TAG
 import pl.treksoft.kvision.html.Tag
 import pl.treksoft.kvision.panel.SimplePanel
-import pl.treksoft.kvision.core.StringBoolPair
 import kotlin.js.Json
 
-enum class FORMTYPE(val formType: String) {
+/**
+ * Bootstrap form layout options.
+ */
+enum class FORMTYPE(internal val formType: String) {
     INLINE("form-inline"),
     HORIZONTAL("form-horizontal")
 }
 
+/**
+ * Bootstrap form component.
+ *
+ * @constructor
+ * @param K model class type
+ * @param type form layout
+ * @param classes set of CSS class names
+ * @param modelFactory function transforming a Map<String, Any?> to a data model of class K
+ */
 open class FormPanel<K>(
     private val type: FORMTYPE? = null, classes: Set<String> = setOf(),
     modelFactory: (Map<String, Any?>) -> K
 ) : SimplePanel(classes) {
 
+    /**
+     * Function returning validation message.
+     */
     var validatorMessage
         get() = form.validatorMessage
         set(value) {
             form.validatorMessage = value
         }
+    /**
+     * Validation function.
+     */
     var validator
         get() = form.validator
         set(value) {
@@ -38,8 +77,16 @@ open class FormPanel<K>(
             refresh()
         }
 
+    /**
+     * @suppress
+     * Internal property.
+     */
     @Suppress("LeakingThis")
     protected val form = Form(this, modelFactory)
+    /**
+     * @suppress
+     * Internal property.
+     */
     protected val validationAlert = Tag(TAG.H5, classes = setOf("alert", "alert-danger")).apply {
         role = "alert"
         visible = false
@@ -50,7 +97,7 @@ open class FormPanel<K>(
     }
 
     override fun render(): VNode {
-        return kvh("form", childrenVNodes())
+        return render("form", childrenVNodes())
     }
 
     override fun getSnClass(): List<StringBoolPair> {
@@ -61,6 +108,15 @@ open class FormPanel<K>(
         return cl
     }
 
+    /**
+     * Adds a control to the form panel.
+     * @param key key identifier of the control
+     * @param control the form control
+     * @param required determines if the control is required
+     * @param validatorMessage optional function returning validation message
+     * @param validator optional validation function
+     * @return current form panel
+     */
     open fun <C : FormControl> add(
         key: String, control: C, required: Boolean = false,
         validatorMessage: ((C) -> String?)? = null,
@@ -82,7 +138,12 @@ open class FormPanel<K>(
         return this
     }
 
-    fun remove(key: String): FormPanel<K> {
+    /**
+     * Removes a control from the form panel.
+     * @param key key identifier of the control
+     * @return current form panel
+     */
+    open fun remove(key: String): FormPanel<K> {
         form.getControl(key)?.let {
             super.remove(it)
         }
@@ -97,30 +158,59 @@ open class FormPanel<K>(
         return this
     }
 
+    /**
+     * Returns a control of given key.
+     * @param key key identifier of the control
+     * @return selected control
+     */
     open fun getControl(key: String): FormControl? {
         return form.getControl(key)
     }
 
+    /**
+     * Returns a value of the control of given key.
+     * @param key key identifier of the control
+     * @return value of the control
+     */
     operator fun get(key: String): Any? {
         return getControl(key)?.getValue()
     }
 
-    open fun setData(data: K) {
-        form.setData(data)
+    /**
+     * Sets the values of all the controls from the model.
+     * @param model data model
+     */
+    open fun setData(model: K) {
+        form.setData(model)
     }
 
+    /**
+     * Sets the values of all controls to null.
+     */
     open fun clearData() {
         form.clearData()
     }
 
+    /**
+     * Returns current data model.
+     * @return data model
+     */
     open fun getData(): K {
         return form.getData()
     }
 
+    /**
+     * Returns current data model as JSON.
+     * @return data model as JSON
+     */
     open fun getDataJson(): Json {
         return form.getDataJson()
     }
 
+    /**
+     * Invokes validator function and validates the form.
+     * @return validation result
+     */
     open fun validate(): Boolean {
         return form.validate()
     }
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/HelpBlock.kt b/src/main/kotlin/pl/treksoft/kvision/form/HelpBlock.kt
index dcfd185e..db9aebc5 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/HelpBlock.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/HelpBlock.kt
@@ -1,8 +1,36 @@
+/*
+ * 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
 
 import pl.treksoft.kvision.html.TAG
 import pl.treksoft.kvision.html.Tag
 
+/**
+ * Helper class for Bootstrap help block element.
+ *
+ * @constructor
+ * @param text the text of the label
+ * @param rich determines if [text] can contain HTML code
+ */
 open class HelpBlock(text: String? = null, rich: Boolean = false) : Tag(
     TAG.SPAN, text, rich,
     classes = setOf("help-block", "small")
diff --git a/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt b/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt
index ea41c429..0bad8440 100644
--- a/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt
+++ b/src/main/kotlin/pl/treksoft/kvision/form/check/CheckBox.kt
@@ -1,15 +1,39 @@
+/*
+ * 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.check
 
 import org.w3c.dom.events.MouseEvent
+import pl.treksoft.kvision.core.StringBoolPair
 import pl.treksoft.kvision.core.Widget
 import pl.treksoft.kvision.form.BoolFormControl
 import pl.treksoft.kvision.form.FieldLabel
 import pl.treksoft.kvision.form.HelpBlock
 import pl.treksoft.kvision.panel.SimplePanel
 import pl.treksoft.kvision.utils.SnOn
-import pl.treksoft.kvision.core.StringBoolPair
 
-enum class CHECKBOXSTYLE(val className: String) {
+/**
+ * Checkbox style options.
+ */
+enum class CHECKBOXSTYLE(internal val className: String) {
     DEFAULT("checkbox-default"),
     PRIMARY("checkbox-primary"),
     SUCCESS("checkbox-success"),
@@ -18,21 +42,41 @@ enum class CHECKBOXSTYLE(val className: String) {
     DANGER("checkbox-danger"),
 }
 
+/**
+ * The form field component rendered as HTML *input type="checkbox"*.
+ *
+ * @constructor
+ * @param value selection state
+ * @param label label text bound to the input element
+ * @param rich determines if [label] can contain HTML code
+ */
 open class CheckBox(
     value: Boolean = false, label: String? = null,
     rich: Boolean = false
 ) : SimplePanel(setOf("checkbox")), BoolFormControl {
 
+    /**
+     * The selection state of the checkbox.
+     */
     override var value
         get() = input.value
         set(value) {
             input.value = value
         }
+    /**
+     * The value attribute of the generated HTML input element.
+     *
+     * This value is placed directly in generated HTML code, while the [value] property is dynamically
+     * bound to the input selection state.
+     */
     var startValue
         get() = input.startValue
         set(value) {
             input.startValue = value
         }
+    /**
+     * The name attribute of the generated HTML input element.
+     */
     var name
         get() = input.name
         set(value) {
@@ -43,31 +87,49 @@ open class CheckBox(
         set(value) {
             input.disabled = value
         }
+    /**
+     * The label text bound to the input 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) {
             flabel.rich = value
         }
+    /**
+     * The style (one of Bootstrap standard colors) of the input.
+     */
     var style: CHECKBOXSTYLE? = null
         set(value) {
             field = value
             refresh()
         }
+    /**
+     * Determines if the checkbox is rendered as a circle.
+     */
     var circled: Boolean = false
         set(value) {
             field = value
             refresh()
         }</