update comments for entity attachment

Author: vincentlauvlwj

ktorm-core/src/main/kotlin/org/ktorm/entity/Entity.kt

@@ -150,15 +150,14 @@ public interface Entity<E : Entity<E>> : Serializable {
      * Using this function, we need to note that:
      *
      * 1. This function requires a primary key specified in the table object via [Table.primaryKey],
-     * otherwise Ktorm doesn’t know how to identify entity objects, then throws an exception.
+     * otherwise Ktorm doesn’t know how to identify entity objects and will throw an exception.
      *
-     * 2. The entity object calling this function must **be associated with a table** first. In Ktorm’s implementation,
-     * every entity object holds a reference `fromTable`, that means this object is associated with the table or was
-     * obtained from it. For entity objects obtained by sequence APIs, their `fromTable` references point to the current
-     * table object they are obtained from. But for entity objects created by [Entity.create] or [Entity.Factory], their
-     * `fromTable` references are `null` initially, so we can not call [flushChanges] on them. But once we use them with
-     * [add] or [update] function of entity sequences, Ktorm will modify their `fromTable` to the current table object,
-     * then we can call [flushChanges] on them afterwards.
+     * 2. The entity object calling this function must be ATTACHED to the database first. In Ktorm’s implementation,
+     * every entity object holds a reference `fromDatabase`. For entity objects obtained by sequence APIs, their
+     * `fromDatabase` references point to the database they are obtained from. For entity objects created by
+     * [Entity.create] or [Entity.Factory], their `fromDatabase` references are `null` initially, so we can not call
+     * [flushChanges] on them. But once we use them with [add] or [update] function, `fromDatabase` will be modified
+     * to the current database, so we will be able to call [flushChanges] on them afterwards.
      *
      * @see add
      * @see update
@@ -182,7 +181,7 @@ public interface Entity<E : Entity<E>> : Serializable {
      * 1. The function requires a primary key specified in the table object via [Table.primaryKey],
      * otherwise, Ktorm doesn’t know how to identify entity objects.
      *
-     * 2. The entity object calling this function must **be associated with a table** first.
+     * 2. The entity object calling this function must be ATTACHED to the database first.
      *
      * @see add
      * @see update

ktorm-core/src/main/kotlin/org/ktorm/entity/EntityDml.kt

@@ -30,7 +30,7 @@ import org.ktorm.schema.*
  * not to set the primary key’s value beforehand, otherwise, if you do that, the given value will be inserted
  * into the database, and no keys generated.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -91,7 +91,7 @@ public fun <E : Entity<E>, T : Table<E>> EntitySequence<E, T>.add(entity: E): In
 /**
  * Update properties of the given entity to the database and return the affected record number.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -148,10 +148,10 @@ public fun <E : Any, T : BaseTable<E>> EntitySequence<E, T>.clear(): Int {
 
 @Suppress("UNCHECKED_CAST")
 internal fun EntityImplementation.doFlushChanges(): Int {
-    check(parent == null) { "The entity is not associated with any database yet." }
+    check(parent == null) { "The entity is not attached to any database yet." }
 
-    val fromDatabase = fromDatabase ?: error("The entity is not associated with any database yet.")
-    val fromTable = fromTable ?: error("The entity is not associated with any table yet.")
+    val fromDatabase = fromDatabase ?: error("The entity is not attached to any database yet.")
+    val fromTable = fromTable ?: error("The entity is not attached to any database yet.")
     checkUnexpectedDiscarding(fromTable)
 
     val assignments = findChangedColumns(fromTable).takeIf { it.isNotEmpty() } ?: return 0
@@ -174,10 +174,10 @@ internal fun EntityImplementation.doFlushChanges(): Int {
 
 @Suppress("UNCHECKED_CAST")
 internal fun EntityImplementation.doDelete(): Int {
-    check(parent == null) { "The entity is not associated with any database yet." }
+    check(parent == null) { "The entity is not attached to any database yet." }
 
-    val fromDatabase = fromDatabase ?: error("The entity is not associated with any database yet.")
-    val fromTable = fromTable ?: error("The entity is not associated with any table yet.")
+    val fromDatabase = fromDatabase ?: error("The entity is not attached to any database yet.")
+    val fromTable = fromTable ?: error("The entity is not attached to any database yet.")
 
     val expression = AliasRemover.visit(
         expr = DeleteExpression(
@@ -272,8 +272,8 @@ private fun EntityImplementation.findChangedColumns(fromTable: Table<*>): Map<Co
 }
 
 internal fun EntityImplementation.doDiscardChanges() {
-    check(parent == null) { "The entity is not associated with any database yet." }
-    val fromTable = fromTable ?: error("The entity is not associated with any table yet.")
+    check(parent == null) { "The entity is not attached to any database yet." }
+    val fromTable = fromTable ?: error("The entity is not attached to any database yet.")
 
     for (column in fromTable.columns) {
         val binding = column.binding ?: continue

ktorm-global/src/main/kotlin/org/ktorm/global/EntitySequence.kt

@@ -30,16 +30,15 @@ public fun <E : Any, T : BaseTable<E>> T.asSequence(withReferences: Boolean = tr
 }
 
 /**
- * Insert the given entity into this table and return the affected record number. Only non-null properties
- * are inserted.
+ * Insert the given entity into this sequence and return the affected record number.
  *
  * If we use an auto-increment key in our table, we need to tell Ktorm which is the primary key by calling
- * [Table.primaryKey] function while registering columns, then this function will obtain the generated key
- * from the database and fill it into the corresponding property after the insertion completes. But this
- * requires us not to set the primary key’s value beforehand, otherwise, if you do that, the given value
- * will be inserted into the database, and no keys generated.
+ * [Table.primaryKey] while registering columns, then this function will obtain the generated key from the
+ * database and fill it into the corresponding property after the insertion completes. But this requires us
+ * not to set the primary key’s value beforehand, otherwise, if you do that, the given value will be inserted
+ * into the database, and no keys generated.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -53,16 +52,15 @@ public fun <E : Entity<E>> Table<E>.add(entity: E): Int {
 }
 
 /**
- * Insert the given entity into this table and return the affected record number. Only non-null properties
- * are inserted.
+ * Insert the given entity into this sequence and return the affected record number.
  *
  * If we use an auto-increment key in our table, we need to tell Ktorm which is the primary key by calling
- * [Table.primaryKey] function while registering columns, then this function will obtain the generated key
- * from the database and fill it into the corresponding property after the insertion completes. But this
- * requires us not to set the primary key’s value beforehand, otherwise, if you do that, the given value
- * will be inserted into the database, and no keys generated.
+ * [Table.primaryKey] while registering columns, then this function will obtain the generated key from the
+ * database and fill it into the corresponding property after the insertion completes. But this requires us
+ * not to set the primary key’s value beforehand, otherwise, if you do that, the given value will be inserted
+ * into the database, and no keys generated.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete
@@ -72,9 +70,9 @@ public fun <E : Entity<E>> Table<E>.addEntity(entity: E): Int {
 }
 
 /**
- * Update the non-null properties of the given entity to the database and return the affected record number.
+ * Update properties of the given entity to the database and return the affected record number.
  *
- * Note that after calling this function, the [entity] will **be associated with the current table**.
+ * Note that after calling this function, the [entity] will be ATTACHED to the current database.
  *
  * @see Entity.flushChanges
  * @see Entity.delete