From 4fd9e894a4e58d03a5d919533399324ce6a31116 Mon Sep 17 00:00:00 2001
From: Chantal Loncle <82039410+bog-walk@users.noreply.github.com>
Date: Fri, 1 Mar 2024 15:49:30 -0500
Subject: [PATCH] docs: Add missing KDocs for exposed-dao InnerTableLink API

Add KDocs in `exposed-dao` to files relating to InnerTableLink.
---
 .../org/jetbrains/exposed/dao/InnerTableLink.kt    | 14 ++++++++++++++
 .../sql/tests/shared/entities/EntityTests.kt       |  2 +-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/InnerTableLink.kt b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/InnerTableLink.kt
index bb26efb980..00cb647537 100644
--- a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/InnerTableLink.kt
+++ b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/InnerTableLink.kt
@@ -9,6 +9,18 @@ import org.jetbrains.exposed.sql.transactions.TransactionManager
 import kotlin.properties.ReadWriteProperty
 import kotlin.reflect.KProperty
 
+/**
+ * Class responsible for implementing property delegates of the read-write properties involved in a many-to-many
+ * relation, which uses an intermediate (join) table.
+ *
+ * @param table The intermediate table containing reference columns to both child and parent entities.
+ * @param sourceTable The [IdTable] associated with the source child entity.
+ * @param target The [EntityClass] for the target parent entity.
+ * @param _sourceColumn The intermediate table's reference column for the child entity class. If left `null`,
+ * this will be inferred from the provided intermediate [table] columns.
+ * @param _targetColumn The intermediate table's reference column for the parent entity class. If left `null`,
+ * this will be inferred from the provided intermediate [table] columns.
+ */
 @Suppress("UNCHECKED_CAST")
 class InnerTableLink<SID : Comparable<SID>, Source : Entity<SID>, ID : Comparable<ID>, Target : Entity<ID>>(
     val table: Table,
@@ -35,10 +47,12 @@ class InnerTableLink<SID : Comparable<SID>, Source : Entity<SID>, ID : Comparabl
         }
     }
 
+    /** The reference identity column for the child entity class. */
     val sourceColumn = _sourceColumn
         ?: table.columns.singleOrNull { it.referee == sourceTable.id } as? Column<EntityID<SID>>
         ?: error("Table does not reference source")
 
+    /** The reference identity column for the parent entity class. */
     val targetColumn = _targetColumn
         ?: table.columns.singleOrNull { it.referee == target.table.id } as? Column<EntityID<ID>>
         ?: error("Table does not reference target")
diff --git a/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt b/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt
index 0cbf09ddab..24af0a7c75 100644
--- a/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt
+++ b/exposed-tests/src/test/kotlin/org/jetbrains/exposed/sql/tests/shared/entities/EntityTests.kt
@@ -89,7 +89,7 @@ object EntityTestsData {
 
     class YEntity(id: EntityID<String>) : Entity<String>(id) {
         var x by YTable.x
-        val b by BEntity.backReferencedOn(XTable.y1)
+        val b: BEntity? by BEntity.backReferencedOn(XTable.y1)
         var content by YTable.blob
 
         companion object : EntityClass<String, YEntity>(YTable)