From 2c5b0917001911dcafca90e069501b44116448d4 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/EntityClass.kt | 1 - .../org/jetbrains/exposed/dao/InnerTableLink.kt | 14 ++++++++++++++ .../kotlin/org/jetbrains/exposed/dao/References.kt | 8 ++++---- .../sql/tests/shared/entities/EntityTests.kt | 2 +- 4 files changed, 19 insertions(+), 6 deletions(-) diff --git a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt index 1d8072a206..9dbe15f03c 100644 --- a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt +++ b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/EntityClass.kt @@ -333,7 +333,6 @@ abstract class EntityClass, out T : Entity>( * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Parent * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Children * @sample org.jetbrains.exposed.sql.tests.shared.entities.EntityTests.Child - * */ infix fun > referencedOn(column: Column) = registerRefRule(column) { Reference(column, this) } 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, Source : Entity, ID : Comparable, Target : Entity>( val table: Table, @@ -35,10 +47,12 @@ class InnerTableLink, Source : Entity, ID : Comparabl } } + /** The reference identity column for the child entity class. */ val sourceColumn = _sourceColumn ?: table.columns.singleOrNull { it.referee == sourceTable.id } as? Column> ?: 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> ?: error("Table does not reference target") diff --git a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt index 440a67f302..d85c1fad1a 100644 --- a/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt +++ b/exposed-dao/src/main/kotlin/org/jetbrains/exposed/dao/References.kt @@ -20,7 +20,7 @@ private fun checkReference(reference: Column<*>, factoryTable: IdTable<*>) { } /** - * Class representing a table relation between 2 [Entity] classes, which is responsible for + * Class representing a table relation between two [Entity] classes, which is responsible for * retrieving the parent entity referenced by the child entity. * * @param reference The reference column defined on the child entity's associated table. @@ -36,7 +36,7 @@ class Reference, ID : Comparable, out Target : Entity< } /** - * Class representing an optional table relation between 2 [Entity] classes, which is responsible for + * Class representing an optional table relation between two [Entity] classes, which is responsible for * retrieving the parent entity optionally referenced by the child entity. * * @param reference The nullable reference column defined on the child entity's associated table. @@ -53,7 +53,7 @@ class OptionalReference, ID : Comparable, out Target : /** * Class responsible for implementing property delegates of the read-only properties involved in a table - * relation between 2 [Entity] classes, which retrieves the child entity that references the parent entity. + * relation between two [Entity] classes, which retrieves the child entity that references the parent entity. * * @param reference The reference column defined on the child entity's associated table. * @param factory The [EntityClass] associated with the child entity that references the parent entity. @@ -70,7 +70,7 @@ internal class BackReference, out Parent : Entit /** * Class responsible for implementing property delegates of the read-only properties involved in an optional table - * relation between 2 [Entity] classes, which retrieves the child entity that optionally references the parent entity. + * relation between two [Entity] classes, which retrieves the child entity that optionally references the parent entity. * * @param reference The nullable reference column defined on the child entity's associated table. * @param factory The [EntityClass] associated with the child entity that optionally references the parent entity. 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) : Entity(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(YTable)