From 543023d2df721683b77cec33e8ac377e0c911355 Mon Sep 17 00:00:00 2001
From: Iaroslav Postovalov <postovalovya@gmail.com>
Date: Sun, 9 May 2021 15:19:07 +0700
Subject: [PATCH] Documentation for ExposedTable

---
 .../dataforge/exposed/ExposedTable.kt         | 76 +++++++++++++++++--
 1 file changed, 71 insertions(+), 5 deletions(-)

diff --git a/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt b/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt
index 2f79b604..81c3cb29 100644
--- a/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt
+++ b/dataforge-exposed/src/main/kotlin/space/kscience/dataforge/exposed/ExposedTable.kt
@@ -1,6 +1,5 @@
 package space.kscience.dataforge.exposed
 
-import org.jetbrains.exposed.dao.id.EntityID
 import org.jetbrains.exposed.dao.id.IntIdTable
 import org.jetbrains.exposed.sql.*
 import org.jetbrains.exposed.sql.transactions.transaction
@@ -12,26 +11,55 @@ import kotlin.reflect.KType
 import kotlin.reflect.typeOf
 import org.jetbrains.exposed.sql.Column as SqlColumn
 
+/**
+ * Exposed based [Column] implementation.
+ *
+ * @param T The type of table items.
+ * @property db The Exposed database.
+ * @param sqlTable The Exposed table, which must follow the properties defined for [ExposedTable.sqlTable].
+ * @param sqlColumn The Exposed column.
+ * @param type The type of [T].
+ */
 public class ExposedColumn<T : Any>(
     public val db: Database,
     public val sqlTable: IntIdTable,
     public val sqlColumn: SqlColumn<T>,
     public override val type: KType,
 ) : Column<T> {
+    /**
+     * The name of this column.
+     */
     public override val name: String
         get() = sqlColumn.name
 
+    /**
+     * Returns [Meta.EMPTY] because it is impossible to store metadata correctly with SQL columns.
+     */
     public override val meta: Meta
         get() = Meta.EMPTY
 
+    /**
+     * Returns the count of rows in the table.
+     */
     public override val size: Int
         get() = transaction(db) { sqlColumn.table.selectAll().count().toInt() }
 
+    /**
+     * Acquires the value of this column in the row [index].
+     */
     public override fun get(index: Int): T? = transaction(db) {
         sqlTable.select { sqlTable.id eq index + 1 }.firstOrNull()?.getOrNull(sqlColumn)
     }
 }
 
+/**
+ * Exposed based [Row] implementation.
+ *
+ * @param T The type of table items.
+ * @param db The Exposed database.
+ * @param sqlTable The Exposed table, which must follow the properties defined for [ExposedTable.sqlTable].
+ * @param sqlRow The Exposed row.
+ */
 @Suppress("UNCHECKED_CAST")
 public class ExposedRow<T : Any>(
     public val db: Database,
@@ -39,19 +67,39 @@ public class ExposedRow<T : Any>(
     public val sqlRow: ResultRow,
 ) :
     Row<T> {
+    /**
+     * Acquires the value of [column] in this row.
+     */
     public override fun get(column: String): T? = transaction(db) {
         val theColumn = sqlTable.columns.find { it.name == column } as SqlColumn<T>? ?: return@transaction null
         sqlRow.getOrNull(theColumn)
     }
 }
 
+/**
+ * Exposed based [Table] implementation.
+ *
+ * @property db The Exposed database.
+ *
+ * @property sqlTable The Exposed table. It must have the following properties:
+ * 1. Integer `id` column must be present with auto-increment by sequence 1, 2, 3&hellip;
+ * 1. All other columns must be of type [T].
+ *
+ * @property type The type of [T].
+ */
 @Suppress("UNCHECKED_CAST")
 public class ExposedTable<T : Any>(public val db: Database, public val sqlTable: IntIdTable, public val type: KType) :
     Table<T> {
-    public override val columns: List<Column<T>> =
+    /**
+     * The list of columns in this table.
+     */
+    public override val columns: List<ExposedColumn<T>> =
         sqlTable.columns.filterNot { it.name == "id" }.map { ExposedColumn(db, sqlTable, it as SqlColumn<T>, type) }
 
-    public override val rows: List<Row<T>>
+    /**
+     * The list of rows in this table.
+     */
+    public override val rows: List<ExposedRow<T>>
         get() = transaction(db) {
             sqlTable.selectAll().map { ExposedRow(db, sqlTable, it) }
         }
@@ -64,9 +112,27 @@ public class ExposedTable<T : Any>(public val db: Database, public val sqlTable:
     }
 }
 
-public inline fun <reified T : Any> ExposedTable(db: Database, table: IntIdTable): ExposedTable<T> =
-    ExposedTable(db, table, typeOf<T>())
+/**
+ * Constructs [ExposedTable].
+ *
+ * @param T The type of table items.
+ * @param db The Exposed database.
+ * @param sqlTable The Exposed table, which must follow the properties defined for [ExposedTable.sqlTable].
+ * @return A new [ExposedTable].
+ */
+public inline fun <reified T : Any> ExposedTable(db: Database, sqlTable: IntIdTable): ExposedTable<T> =
+    ExposedTable(db, sqlTable, typeOf<T>())
 
+/**
+ * Constructs [ExposedTable].
+ *
+ * @param T The type of table items.
+ * @param db The Exposed database.
+ * @param tableName The name of table.
+ * @param columns The list of columns' names.
+ * @param sqlColumnType The [IColumnType] for [T].
+ * @return A new [ExposedTable].
+ */
 public inline fun <reified T : Any> ExposedTable(
     db: Database,
     tableName: String,
-- 
2.34.1