docs: Add missing KDocs for public API

Add applicable samples where possible.

Adjust KDocs on class properties that don't return.

Refactor description of spring boot DatabaseInitializer.

exposed-crypt/src/main/kotlin/org/jetbrains/exposed/crypt/Algorithms.kt

@@ -11,6 +11,8 @@ import kotlin.math.ceil
 
 /**
  * Symmetric-key block ciphers for performing encryption and decryption.
+ *
+ * @sample org.jetbrains.exposed.sql.tests.shared.dml.SelectTests.testEncryptedColumnTypeWithAString
  */
 object Algorithms {
     @Suppress("MagicNumber")

exposed-crypt/src/main/kotlin/org/jetbrains/exposed/crypt/EncryptedBinaryColumnType.kt

@@ -4,6 +4,8 @@ import org.jetbrains.exposed.sql.BinaryColumnType
 
 /**
  * Binary column for storing encrypted binary strings of a specific [length], using the provided [encryptor].
+ *
+ * @sample org.jetbrains.exposed.crypt.encryptedBinary
  */
 class EncryptedBinaryColumnType(
     private val encryptor: Encryptor,

exposed-crypt/src/main/kotlin/org/jetbrains/exposed/crypt/EncryptedVarCharColumnType.kt

@@ -5,6 +5,8 @@ import org.jetbrains.exposed.sql.VarCharColumnType
 /**
  * Character column for storing encrypted strings, using the provided [encryptor],
  * with the specified maximum [colLength].
+ *
+ * @sample org.jetbrains.exposed.crypt.encryptedVarchar
  */
 class EncryptedVarCharColumnType(
     private val encryptor: Encryptor,

exposed-crypt/src/main/kotlin/org/jetbrains/exposed/crypt/Encryptor.kt

@@ -2,13 +2,15 @@ package org.jetbrains.exposed.crypt
 
 /**
  * Base cipher class responsible for the encryption and decryption of data.
+ *
+ * @sample org.jetbrains.exposed.crypt.Algorithms.AES_256_PBE_GCM
  */
 class Encryptor(
-    /** Returns the function that converts a plaintext String to ciphertext. */
+    /** Encrypt a plaintext string to ciphertext. */
     val encryptFn: (String) -> String,
-    /** Returns the function that converts ciphertext to a plaintext String. */
+    /** Decrypt ciphertext to a plaintext string. */
     val decryptFn: (String) -> String,
-    /** Returns the function that converts the expected input length into the maximum encoded length to be stored. */
+    /** Convert the expected input length into the maximum encoded length to be stored. */
     val maxColLengthFn: (Int) -> Int
 ) {
     /** Returns an encrypted value using [encryptFn]. */

exposed-crypt/src/main/kotlin/org/jetbrains/exposed/crypt/Tables.kt

@@ -9,6 +9,7 @@ import org.jetbrains.exposed.sql.Table
  * @param name Name of the column
  * @param cipherTextLength Maximum expected length of encrypted value
  * @param encryptor [Encryptor] responsible for performing encryption and decryption of stored values
+ * @sample org.jetbrains.exposed.sql.tests.shared.dml.SelectTests.testEncryptedColumnTypeWithAString
  */
 fun Table.encryptedVarchar(name: String, cipherTextLength: Int, encryptor: Encryptor): Column<String> =
     registerColumn(name, EncryptedVarCharColumnType(encryptor, cipherTextLength))
@@ -19,6 +20,7 @@ fun Table.encryptedVarchar(name: String, cipherTextLength: Int, encryptor: Encry
  * @param name Name of the column
  * @param cipherByteLength Maximum expected length of encrypted value in bytes
  * @param encryptor [Encryptor] responsible for performing encryption and decryption of stored values
+ * @sample org.jetbrains.exposed.sql.tests.shared.dml.SelectTests.testEncryptedColumnTypeWithAString
  */
 fun Table.encryptedBinary(name: String, cipherByteLength: Int, encryptor: Encryptor): Column<ByteArray> =
     registerColumn(name, EncryptedBinaryColumnType(encryptor, cipherByteLength))

exposed-java-time/src/main/kotlin/org/jetbrains/exposed/sql/javatime/JavaDateColumnType.kt

@@ -82,7 +82,9 @@ internal fun dateTimeWithFractionFormat(fraction: Int): DateTimeFormatter {
 internal val LocalDate.millis get() = atStartOfDay(ZoneId.systemDefault()).toEpochSecond() * 1000
 
 /**
- * Column for storing dates.
+ * Column for storing dates, as [LocalDate].
+ *
+ * @sample org.jetbrains.exposed.sql.javatime.date
  */
 @Suppress("MagicNumber")
 class JavaLocalDateColumnType : ColumnType(), IDateColumnType {
@@ -129,7 +131,9 @@ class JavaLocalDateColumnType : ColumnType(), IDateColumnType {
 }
 
 /**
- * Column for storing dates and times without time zone.
+ * Column for storing dates and times without time zone, as [LocalDateTime].
+ *
+ * @sample org.jetbrains.exposed.sql.javatime.datetime
  */
 @Suppress("MagicNumber")
 class JavaLocalDateTimeColumnType : ColumnType(), IDateColumnType {
@@ -183,7 +187,9 @@ class JavaLocalDateTimeColumnType : ColumnType(), IDateColumnType {
 }
 
 /**
- * Column for storing times.
+ * Column for storing times, as [LocalTime].
+ *
+ * @sample org.jetbrains.exposed.sql.javatime.time
  */
 class JavaLocalTimeColumnType : ColumnType(), IDateColumnType {
     override val hasTimePart: Boolean = true
@@ -237,7 +243,9 @@ class JavaLocalTimeColumnType : ColumnType(), IDateColumnType {
 }
 
 /**
- * Column for storing dates and times without time zone, as an `Instant`.
+ * Column for storing dates and times without time zone, as [Instant].
+ *
+ * @sample org.jetbrains.exposed.sql.javatime.timestamp
  */
 class JavaInstantColumnType : ColumnType(), IDateColumnType {
     override val hasTimePart: Boolean = true
@@ -283,7 +291,9 @@ class JavaInstantColumnType : ColumnType(), IDateColumnType {
 }
 
 /**
- * Column for storing dates and times with time zone.
+ * Column for storing dates and times with time zone, as [OffsetDateTime].
+ *
+ * @sample org.jetbrains.exposed.sql.javatime.timestampWithTimeZone
  */
 class JavaOffsetDateTimeColumnType : ColumnType(), IDateColumnType {
     override val hasTimePart: Boolean = true
@@ -336,7 +346,9 @@ class JavaOffsetDateTimeColumnType : ColumnType(), IDateColumnType {
 }
 
 /**
- * Column for storing time-based amounts of time, as a `Duration`.
+ * Column for storing time-based amounts of time, as [Duration].
+ *
+ * @sample org.jetbrains.exposed.sql.javatime.duration
  */
 class JavaDurationColumnType : ColumnType() {
     override fun sqlType(): String = currentDialect.dataTypeProvider.longType()

exposed-java-time/src/main/kotlin/org/jetbrains/exposed/sql/javatime/JavaDateFunctions.kt

@@ -25,7 +25,11 @@ class Time<T : Temporal?>(val expr: Expression<T>) : Function<LocalTime>(JavaLoc
     override fun toQueryBuilder(queryBuilder: QueryBuilder) = queryBuilder { append("Time(", expr, ")") }
 }
 
-/** Represents an SQL function that returns the current date and time, as a `LocalDateTime`. */
+/**
+ * Represents an SQL function that returns the current date and time, as [LocalDateTime].
+ *
+ * @sample org.jetbrains.exposed.DefaultsTest.testConsistentSchemeWithFunctionAsDefaultExpression
+ */
 object CurrentDateTime : Function<LocalDateTime>(JavaLocalDateTimeColumnType.INSTANCE) {
     override fun toQueryBuilder(queryBuilder: QueryBuilder) = queryBuilder {
         +when {
@@ -35,7 +39,11 @@ object CurrentDateTime : Function<LocalDateTime>(JavaLocalDateTimeColumnType.INS
     }
 }
 
-/** Represents an SQL function that returns the current date. */
+/**
+ * Represents an SQL function that returns the current date, as [LocalDate].
+ *
+ * @sample org.jetbrains.exposed.DefaultsTest.testConsistentSchemeWithFunctionAsDefaultExpression
+ */
 object CurrentDate : Function<LocalDate>(JavaLocalDateColumnType.INSTANCE) {
     override fun toQueryBuilder(queryBuilder: QueryBuilder) = queryBuilder {
         +when (currentDialect) {
@@ -46,7 +54,11 @@ object CurrentDate : Function<LocalDate>(JavaLocalDateColumnType.INSTANCE) {
     }
 }
 
-/** Represents an SQL function that returns the current date and time. */
+/**
+ * Represents an SQL function that returns the current date and time.
+ *
+ * @sample org.jetbrains.exposed.DefaultsTest.testConsistentSchemeWithFunctionAsDefaultExpression
+ */
 class CurrentTimestamp<T : Temporal> : Function<T>(JavaInstantColumnType.INSTANCE) {
     override fun toQueryBuilder(queryBuilder: QueryBuilder) = queryBuilder {
         +when {

exposed-jodatime/src/main/kotlin/org/jetbrains/exposed/sql/jodatime/DateColumnType.kt

@@ -47,7 +47,9 @@ private fun dateTimeWithFractionFormat(fraction: Int): DateTimeFormatter {
 }
 
 /**
- * Column for storing dates. If [time] is set to `true`, both date and time data is stored.
+ * Column for storing dates, as [DateTime]. If [time] is set to `true`, both date and time data is stored.
+ *
+ * @sample org.jetbrains.exposed.sql.jodatime.datetime
  */
 class DateColumnType(val time: Boolean) : ColumnType(), IDateColumnType {
     override val hasTimePart: Boolean = time
@@ -130,7 +132,9 @@ class DateColumnType(val time: Boolean) : ColumnType(), IDateColumnType {
 }
 
 /**
- * Column for storing dates and times with time zone.
+ * Column for storing dates and times with time zone, as [DateTime].
+ *
+ * @sample org.jetbrains.exposed.sql.jodatime.timestampWithTimeZone
  */
 class DateTimeWithTimeZoneColumnType : ColumnType(), IDateColumnType {
     override val hasTimePart: Boolean = true

exposed-jodatime/src/main/kotlin/org/jetbrains/exposed/sql/jodatime/DateFunctions.kt

@@ -14,7 +14,11 @@ class Date<T : DateTime?>(val expr: Expression<T>) : Function<DateTime>(DateColu
     override fun toQueryBuilder(queryBuilder: QueryBuilder) = queryBuilder { append("DATE(", expr, ")") }
 }
 
-/** Represents an SQL function that returns the current date and time. */
+/**
+ * Represents an SQL function that returns the current date and time, as [DateTime]
+ *
+ * @sample org.jetbrains.exposed.JodaTimeDefaultsTest.testDefaultExpressions02
+ */
 object CurrentDateTime : Function<DateTime>(DateColumnType(true)) {
     override fun toQueryBuilder(queryBuilder: QueryBuilder) = queryBuilder {
         +when {
@@ -24,7 +28,11 @@ object CurrentDateTime : Function<DateTime>(DateColumnType(true)) {
     }
 }
 
-/** Represents an SQL function that returns the current date. */
+/**
+ * Represents an SQL function that returns the current date, as [DateTime].
+ *
+ * @sample org.jetbrains.exposed.JodaTimeDefaultsTest.testDefaultExpressions02
+ */
 object CurrentDate : Function<DateTime>(DateColumnType(false)) {
     override fun toQueryBuilder(queryBuilder: QueryBuilder) = queryBuilder {
         +when (currentDialect) {

exposed-json/src/main/kotlin/org/jetbrains/exposed/sql/json/JsonBColumnType.kt

@@ -13,6 +13,7 @@ import org.jetbrains.exposed.sql.vendors.currentDialect
  *
  * @param serialize Function that encodes an object of type [T] to a JSON String
  * @param deserialize Function that decodes a JSON String to an object of type [T]
+ * @sample jsonb
  */
 class JsonBColumnType<T : Any>(
     serialize: (T) -> String,
@@ -51,6 +52,7 @@ fun <T : Any> Table.jsonb(
  * @param jsonConfig Configured instance of the `Json` class
  * @param kSerializer Serializer responsible for the representation of a serial form of type [T].
  * Defaults to a generic serializer for type [T]
+ * @sample org.jetbrains.exposed.sql.json.JsonBColumnTests.testLoggerWithJsonBCollections
  */
 inline fun <reified T : Any> Table.jsonb(
     name: String,

exposed-json/src/main/kotlin/org/jetbrains/exposed/sql/json/JsonColumnType.kt

@@ -15,11 +15,13 @@ import org.postgresql.util.PGobject
 
 /**
  * Column for storing JSON data, either in non-binary text format or the vendor's default JSON type format.
+ *
+ * @sample json
  */
 open class JsonColumnType<T : Any>(
-    /** Returns the function that encodes an object of type [T] to a JSON String. */
+    /** Encode an object of type [T] to a JSON String. */
     val serialize: (T) -> String,
-    /** Returns the function that decodes a JSON String to an object of type [T]. */
+    /** Decode a JSON String to an object of type [T]. */
     val deserialize: (String) -> T
 ) : ColumnType(), JsonColumnMarker {
     override val usesBinaryFormat: Boolean = false
@@ -92,6 +94,7 @@ fun <T : Any> Table.json(
  * @param jsonConfig Configured instance of the `Json` class
  * @param kSerializer Serializer responsible for the representation of a serial form of type [T].
  * Defaults to a generic serializer for type [T]
+ * @sample org.jetbrains.exposed.sql.json.JsonColumnTests.testLoggerWithJsonCollections
  */
 inline fun <reified T : Any> Table.json(
     name: String,

exposed-json/src/main/kotlin/org/jetbrains/exposed/sql/json/JsonConditions.kt

@@ -15,13 +15,13 @@ import org.jetbrains.exposed.sql.vendors.currentDialect
  * Represents an SQL operator that checks whether a [candidate] expression is contained within a JSON [target].
  */
 class Contains(
-    /** Returns the JSON expression being searched. */
+    /** The JSON expression being searched. */
     val target: Expression<*>,
-    /** Returns the expression being searched for in [target]. */
+    /** The expression being searched for in [target]. */
     val candidate: Expression<*>,
-    /** Returns an optional String representing JSON path/keys that match specific fields to search for [candidate]. */
+    /** An optional String representing JSON path/keys that match specific fields to search for [candidate]. */
     val path: String?,
-    /** Returns the column type of [target] to check, if casting to JSONB is required. */
+    /** The column type of [target] to check, if casting to JSONB is required. */
     val jsonType: IColumnType
 ) : Op<Boolean>(), ComplexExpression {
     override fun toQueryBuilder(queryBuilder: QueryBuilder) =
@@ -32,13 +32,13 @@ class Contains(
  * Represents an SQL operator that checks whether data exists within a JSON [expression] at the specified [path].
  */
 class Exists(
-    /** Returns the JSON expression being checked. */
+    /** The JSON expression being checked. */
     val expression: Expression<*>,
-    /** Returns the array of Strings representing JSON path/keys that match fields to check for existing data. */
+    /** The array of Strings representing JSON path/keys that match fields to check for existing data. */
     vararg val path: String,
-    /** Returns an optional String representing any vendor-specific clause or argument. */
+    /** An optional String representing any vendor-specific clause or argument. */
     val optional: String?,
-    /** Returns the column type of [expression] to check, if casting to JSONB is required. */
+    /** The column type of [expression] to check, if casting to JSONB is required. */
     val jsonType: IColumnType
 ) : Op<Boolean>(), ComplexExpression {
     override fun toQueryBuilder(queryBuilder: QueryBuilder) =
@@ -53,6 +53,7 @@ class Exists(
  * @param candidate Expression to search for in [this] JSON expression.
  * @param path String representing JSON path/keys that match specific fields to search for [candidate].
  * **Note:** Optional [path] argument is not supported by all vendors; please check the documentation.
+ * @sample org.jetbrains.exposed.sql.json.JsonColumnTests.testJsonContains
  */
 fun ExpressionWithColumnType<*>.contains(candidate: Expression<*>, path: String? = null): Contains =
     Contains(this, candidate, path, columnType)
@@ -63,6 +64,7 @@ fun ExpressionWithColumnType<*>.contains(candidate: Expression<*>, path: String?
  * @param candidate Value to search for in [this] JSON expression.
  * @param path String representing JSON path/keys that match specific fields to search for [candidate].
  * **Note:** Optional [path] argument is not supported by all vendors; please check the documentation.
+ * @sample org.jetbrains.exposed.sql.json.JsonColumnTests.testJsonContains
  */
 fun <T> ExpressionWithColumnType<*>.contains(candidate: T, path: String? = null): Contains =
     Contains(this, asLiteral(candidate), path, columnType)
@@ -75,6 +77,7 @@ fun <T> ExpressionWithColumnType<*>.contains(candidate: T, path: String? = null)
  * **Note:** Multiple [path] arguments are not supported by all vendors; please check the documentation.
  * @param optional String representing any optional vendor-specific clause or argument.
  * **Note:** [optional] function arguments are not supported by all vendors; please check the documentation.
+ * @sample org.jetbrains.exposed.sql.json.JsonColumnTests.testJsonExists
  */
 fun ExpressionWithColumnType<*>.exists(vararg path: String, optional: String? = null): Exists =
     Exists(this, path = path, optional, columnType)

exposed-json/src/main/kotlin/org/jetbrains/exposed/sql/json/JsonFunctions.kt

@@ -15,13 +15,13 @@ import org.jetbrains.exposed.sql.vendors.currentDialect
  * either as a JSON representation or as a scalar value.
  */
 class Extract<T>(
-    /** Returns the expression from which to extract JSON subcomponents matched by [path]. */
+    /** The expression from which to extract JSON subcomponents matched by [path]. */
     val expression: Expression<*>,
-    /** Returns array of Strings representing JSON path/keys that match fields to be extracted. */
+    /** Array of Strings representing JSON path/keys that match fields to be extracted. */
     vararg val path: String,
-    /** Returns whether the extracted result should be a scalar or text value; if `false`, result will be a JSON object. */
+    /** Whether the extracted result should be a scalar or text value; if `false`, result will be a JSON object. */
     val toScalar: Boolean,
-    /** Returns the column type of [expression] to check, if casting to JSONB is required. */
+    /** The column type of [expression] to check, if casting to JSONB is required. */
     val jsonType: IColumnType,
     columnType: IColumnType
 ) : Function<T>(columnType) {
@@ -38,6 +38,7 @@ class Extract<T>(
  * If none are provided, the root context item `'$'` will be used by default.
  * **Note:** Multiple [path] arguments are not supported by all vendors; please check the documentation.
  * @param toScalar If `true`, the extracted result is a scalar or text value; otherwise, it is a JSON object.
+ * @sample org.jetbrains.exposed.sql.json.JsonColumnTests.testJsonExtractWithArrays
  */
 inline fun <reified T : Any> ExpressionWithColumnType<*>.extract(
     vararg path: String,