core: add KDoc to some constraint builders (#14)

library/src/jvmMain/kotlin/dev/nesk/akkurate/constraints/builders/Any.kt

@@ -22,14 +22,116 @@ import dev.nesk.akkurate.constraints.constrain
 import dev.nesk.akkurate.constraints.otherwise
 import dev.nesk.akkurate.validatables.Validatable
 
+/**
+ * The validatable value must be null when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Int?> { isNull() }
+ * validate(null) // Success
+ * validate(1234) // Failure (message: Must be null)
+ * ```
+ */
 public fun <T> Validatable<T?>.isNull(): Constraint = constrain { it == null } otherwise { "Must be null" }
+
+/**
+ * The validatable value must not be null when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Int?> { isNotNull() }
+ * validate(1234) // Success
+ * validate(null) // Failure (message: Must not be null)
+ * ```
+ */
 public fun <T> Validatable<T?>.isNotNull(): Constraint = constrain { it != null } otherwise { "Must not be null" }
 
+/**
+ * The validatable value must be equal to [other] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<String> { isEqualTo("foo") }
+ * validate("foo") // Success
+ * validate("bar") // Failure (message: Must be equal to "foo")
+ * ```
+ */
 public fun <T> Validatable<T?>.isEqualTo(other: T?): Constraint = constrain { it == other } otherwise { "Must be equal to \"$other\"" }
+
+/**
+ * The validatable value must be equal to [other] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Pair<String, String>> { first.isEqualTo(second) }
+ * validate("foo" to "foo") // Success
+ * validate("foo" to "bar") // Failure (message: Must be equal to "bar")
+ * ```
+ */
 public fun <T> Validatable<T?>.isEqualTo(other: Validatable<T>): Constraint = constrain { it == other.unwrap() } otherwise { "Must be equal to \"${other.unwrap()}\"" }
 
+/**
+ * The validatable value must be different from [other] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<String> { isNotEqualTo("foo") }
+ * validate("bar") // Success
+ * validate("foo") // Failure (message: Must be different from "foo")
+ * ```
+ */
 public fun <T> Validatable<T?>.isNotEqualTo(other: T?): Constraint = constrain { it != other } otherwise { "Must be different from \"$other\"" }
+
+/**
+ * The validatable value must be different from [other] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Pair<String, String>> { first.isNotEqualTo(second) }
+ * validate("foo" to "bar") // Success
+ * validate("foo" to "foo") // Failure (message: Must be different from "foo")
+ * ```
+ */
 public fun <T> Validatable<T?>.isNotEqualTo(other: Validatable<T>): Constraint = constrain { it != other.unwrap() } otherwise { "Must be different from \"${other.unwrap()}\"" }
 
+/**
+ * The validatable value must be identical to [other] when this constraint is applied.
+ *
+ * The values are considered identical [if they are referentially equal.](https://kotlinlang.org/docs/equality.html#referential-equality)
+ *
+ * Code example:
+ *
+ * ```
+ * data object Foo
+ * data object Bar
+ *
+ * val validate = Validator<Any> { isIdenticalTo(Foo) }
+ * validate(Foo) // Success
+ * validate(Bar) // Failure (message: Must be identical to "Foo")
+ * ```
+ */
 public fun <T> Validatable<T?>.isIdenticalTo(other: T?): Constraint = constrain { it === other } otherwise { "Must be identical to \"$other\"" }
+
+/**
+ * The validatable value must not be identical to [other] when this constraint is applied.
+ *
+ * The values are considered not identical [if they are not referentially equal.](https://kotlinlang.org/docs/equality.html#referential-equality)
+ *
+ * Code example:
+ *
+ * ```
+ * data object Foo
+ * data object Bar
+ *
+ * val validate = Validator<Any> { isNotIdenticalTo(Foo) }
+ * validate(Bar) // Success
+ * validate(Foo) // Failure (message: Must not be identical to "Foo")
+ * ```
+ */
 public fun <T> Validatable<T?>.isNotIdenticalTo(other: T?): Constraint = constrain { it !== other } otherwise { "Must not be identical to \"$other\"" }

library/src/jvmMain/kotlin/dev/nesk/akkurate/constraints/builders/Array.kt

@@ -31,46 +31,171 @@ import dev.nesk.akkurate.validatables.Validatable
  * union types in Kotlin, we must duplicate the code for each of those types.
  */
 
+/**
+ * The validatable [Array] must be empty when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { isNotEmpty() }
+ * validate(arrayOf('a', 'b', 'c')) // Success
+ * validate(emptyArray()) // Failure (message: Must not be empty)
+ * ```
+ */
 @JvmName("arrayIsEmpty")
 public fun <T> Validatable<Array<out T>?>.isEmpty(): Constraint =
     constrainIfNotNull { it.isEmpty() } otherwise { "Must be empty" }
 
+/**
+ * The validatable [Array] must not be empty when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { isEmpty() }
+ * validate(emptyArray()) // Success
+ * validate(arrayOf('a', 'b', 'c')) // Failure (message: Must be empty)
+ * ```
+ */
 @JvmName("arrayIsNotEmpty")
 public fun <T> Validatable<Array<out T>?>.isNotEmpty(): Constraint =
     constrainIfNotNull { it.isNotEmpty() } otherwise { "Must not be empty" }
 
+/**
+ * The validatable [Array] must have a size equal to [size] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { hasSizeEqualTo(3) }
+ * validate(arrayOf('a', 'b', 'c')) // Success
+ * validate(arrayOf('a', 'b')) // Failure (message: The number of items must be equal to 3)
+ * ```
+ */
 @JvmName("arrayHasSizeEqualTo")
 public fun <T> Validatable<Array<out T>?>.hasSizeEqualTo(size: Int): Constraint =
     constrainIfNotNull { it.size == size } otherwise { "The number of items must be equal to $size" }
 
+/**
+ * The validatable [Array] must have a size different from [size] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { hasSizeNotEqualTo(3) }
+ * validate(arrayOf('a', 'b')) // Success
+ * validate(arrayOf('a', 'b', 'c')) // Failure (message: The number of items must be different from 3)
+ * ```
+ */
 @JvmName("arrayHasSizeNotEqualTo")
 public fun <T> Validatable<Array<out T>?>.hasSizeNotEqualTo(size: Int): Constraint =
     constrainIfNotNull { it.size != size } otherwise { "The number of items must be different from $size" }
 
+/**
+ * The validatable [Array] must have a size lower than [size] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { hasSizeLowerThan(3) }
+ * validate(arrayOf('a', 'b')) // Success
+ * validate(arrayOf('a', 'b', 'c')) // Failure (message: The number of items must be lower than 3)
+ * ```
+ */
 @JvmName("arrayHasSizeLowerThan")
 public fun <T> Validatable<Array<out T>?>.hasSizeLowerThan(size: Int): Constraint =
     constrainIfNotNull { it.size < size } otherwise { "The number of items must be lower than $size" }
 
+/**
+ * The validatable [Array] must have a size lower than or equal to [size] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { hasSizeLowerThanOrEqualTo(2) }
+ * validate(arrayOf('a')) // Success
+ * validate(arrayOf('a', 'b')) // Success
+ * validate(arrayOf('a', 'b', 'c')) // Failure (message: The number of items must be lower than or equal to 2)
+ * ```
+ */
 @JvmName("arrayHasSizeLowerThanOrEqualTo")
 public fun <T> Validatable<Array<out T>?>.hasSizeLowerThanOrEqualTo(size: Int): Constraint =
     constrainIfNotNull { it.size <= size } otherwise { "The number of items must be lower than or equal to $size" }
 
+/**
+ * The validatable [Array] must have a size greater than [size] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { hasSizeGreaterThan(2) }
+ * validate(arrayOf('a', 'b', 'c')) // Success
+ * validate(arrayOf('a', 'b')) // Failure (message: The number of items must be greater than 2)
+ * ```
+ */
 @JvmName("arrayHasSizeGreaterThan")
 public fun <T> Validatable<Array<out T>?>.hasSizeGreaterThan(size: Int): Constraint =
     constrainIfNotNull { it.size > size } otherwise { "The number of items must be greater than $size" }
 
+/**
+ * The validatable [Array] must have a size greater than or equal to [size] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { hasSizeGreaterThanOrEqualTo(2) }
+ * validate(arrayOf('a', 'b', 'c')) // Success
+ * validate(arrayOf('a', 'b')) // Success
+ * validate(arrayOf('a')) // Failure (message: The number of items must be greater than or equal to 2)
+ * ```
+ */
 @JvmName("arrayHasSizeGreaterThanOrEqualTo")
 public fun <T> Validatable<Array<out T>?>.hasSizeGreaterThanOrEqualTo(size: Int): Constraint =
     constrainIfNotNull { it.size >= size } otherwise { "The number of items must be greater than or equal to $size" }
 
+/**
+ * The validatable [Array] must have a size [within the provided range][range] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { hasSizeBetween(1..2) }
+ * validate(emptyArray()) // Failure (message: The number of items must be between 1 and 2)
+ * validate(arrayOf('a')) // Success
+ * validate(arrayOf('a', 'b')) // Success
+ * validate(arrayOf('a', 'b', 'c')) // Failure (message: The number of items must be between 1 and 2)
+ * ```
+ */
 @JvmName("arrayHasSizeBetween")
 public fun <T> Validatable<Array<out T>?>.hasSizeBetween(range: IntRange): Constraint =
     constrainIfNotNull { it.size in range } otherwise { "The number of items must be between ${range.first} and ${range.last}" }
 
+/**
+ * The validatable [Array] must contain [element] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { isContaining('b') }
+ * validate(arrayOf('a', 'b', 'c')) // Success
+ * validate(emptyArray()) // Failure (message: Must contain "b")
+ * ```
+ */
 @JvmName("arrayIsContaining")
 public fun <T> Validatable<Array<out T>?>.isContaining(element: T): Constraint =
     constrainIfNotNull { it.contains(element) } otherwise { "Must contain \"$element\"" }
 
+/**
+ * The validatable [Array] must not contain [element] when this constraint is applied.
+ *
+ * Code example:
+ *
+ * ```
+ * val validate = Validator<Array<Char>> { isNotContaining('b') }
+ * validate(emptyArray()) // Success
+ * validate(arrayOf('a', 'b', 'c')) // Failure (message: Must not contain "b")
+ * ```
+ */
 @JvmName("arrayIsNotContaining")
 public fun <T> Validatable<Array<out T>?>.isNotContaining(element: T): Constraint =
     constrainIfNotNull { !it.contains(element) } otherwise { "Must not contain \"$element\"" }