docs: Fix foreign key KDocs that swap parent and child references (#2004

) KDocs introduced to the ForeignKeyConstraint data class incorrectly switches parent references table columns with child referencing table columns. The KDocs for the functions that create this constraint have also been cleaned up and samples added.
JetBrains · Feb 22, 2024 · f8ca8ef · f8ca8ef
1 parent 6e44d8f
commit f8ca8ef
Show file tree

Hide file tree

Showing 2 changed files with 88 additions and 78 deletions.
diff --git a/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Constraints.kt b/exposed-core/src/main/kotlin/org/jetbrains/exposed/sql/Constraints.kt
@@ -48,7 +48,7 @@ enum class ReferenceOption {
  * Represents a foreign key constraint.
  */
 data class ForeignKeyConstraint(
-    /** Mapping of referenced parent table columns to the foreign key columns in their child tables. */
+    /** Mapping of the foreign key columns in the referencing child table to their referenced parent table columns. */
     val references: Map<Column<*>, Column<*>>,
     private val onUpdate: ReferenceOption?,
     private val onDelete: ReferenceOption?,
@@ -65,31 +65,31 @@ data class ForeignKeyConstraint(
     private val tx: Transaction
         get() = TransactionManager.current()
 
-    /** The columns of the referencing child table. */
+    /** The columns of the referenced parent table. */
     val target: LinkedHashSet<Column<*>> = LinkedHashSet(references.values)
 
-    /** The referencing child table. */
+    /** The referenced parent table. */
     val targetTable: Table = target.first().table
 
-    /** Name of the child table. */
+    /** Name of the referenced parent table. */
     val targetTableName: String
         get() = tx.identity(targetTable)
 
-    /** Names of the foreign key columns. */
+    /** Names of the referenced parent table columns. */
     private val targetColumns: String
         get() = target.joinToString { tx.identity(it) }
 
-    /** The columns of the referenced parent table. */
+    /** The foreign key columns of the referencing child table. */
     val from: LinkedHashSet<Column<*>> = LinkedHashSet(references.keys)
 
-    /** The referenced parent table. */
+    /** The referencing child table. */
     val fromTable: Table = from.first().table
 
-    /** Name of the parent table. */
+    /** Name of the referencing child table. */
     val fromTableName: String
         get() = tx.identity(fromTable)
 
-    /** Names of the key columns from the parent table. */
+    /** Names of the foreign key columns from the referencing child table. */
     private val fromColumns: String
         get() = from.joinToString { tx.identity(it) }
 
@@ -105,7 +105,7 @@ data class ForeignKeyConstraint(
     val customFkName: String?
         get() = name
 
-    /** Name of this constraint. */
+    /** Name of this foreign key constraint. */
     val fkName: String
         get() = tx.db.identifierManager.cutIfNecessaryAndQuote(
             name ?: (
@@ -168,7 +168,7 @@ data class ForeignKeyConstraint(
         return listOf("ALTER TABLE $fromTableName DROP $constraintType $fkName")
     }
 
-    /** Returns the child table column that is referencing the provided column in the parent table. */
+    /** Returns the parent table column that is referenced by the [from] column in the child table. */
     fun targetOf(from: Column<*>): Column<*>? = references[from]
 
     operator fun plus(other: ForeignKeyConstraint): ForeignKeyConstraint {