From 4df9175593268a9ef194c1ec58d76449c724e332 Mon Sep 17 00:00:00 2001
From: Jeff Butler <jeffgbutler@gmail.com>
Date: Thu, 3 Feb 2022 16:42:19 -0500
Subject: [PATCH 1/4] Update the Kotlin join syntax

---
 .../dynamic/sql/util/kotlin/JoinCollector.kt  | 25 ++++++
 .../sql/util/kotlin/elements/SqlElements.kt   |  1 +
 .../PersonWithAddressMapperExtensions.kt      |  7 +-
 .../mybatis3/general/GeneralKotlinTest.kt     |  7 +-
 .../kotlin/mybatis3/joins/JoinMapperTest.kt   | 85 +++++++++++--------
 ...CanonicalSpringKotlinTemplateDirectTest.kt |  3 +-
 .../canonical/CanonicalSpringKotlinTest.kt    |  3 +-
 7 files changed, 85 insertions(+), 46 deletions(-)

diff --git a/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt b/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt
index 29a6ad32b..417a25ae8 100644
--- a/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt
+++ b/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt
@@ -16,6 +16,7 @@
 package org.mybatis.dynamic.sql.util.kotlin
 
 import org.mybatis.dynamic.sql.BasicColumn
+import org.mybatis.dynamic.sql.SqlBuilder
 import org.mybatis.dynamic.sql.select.join.JoinCondition
 import org.mybatis.dynamic.sql.select.join.JoinCriterion
 
@@ -27,6 +28,25 @@ class JoinCollector {
     val andJoinCriteria = mutableListOf<JoinCriterion>()
     private lateinit var internalOnCriterion: JoinCriterion
 
+    fun on(leftColumn: BasicColumn): RightColumnCollector = RightColumnCollector {
+        internalOnCriterion = JoinCriterion.Builder()
+            .withConnector("on")
+            .withJoinColumn(leftColumn)
+            .withJoinCondition(it)
+            .build()
+    }
+
+    fun and(leftColumn: BasicColumn): RightColumnCollector = RightColumnCollector {
+        andJoinCriteria.add(
+            JoinCriterion.Builder()
+                .withConnector("and")
+                .withJoinColumn(leftColumn)
+                .withJoinCondition(it)
+                .build()
+        )
+    }
+
+    @Deprecated("Please use: on(leftColumn) equalTo rightColumn")
     fun on(column: BasicColumn, condition: JoinCondition): JoinCollector =
         apply {
             internalOnCriterion = JoinCriterion.Builder()
@@ -36,6 +56,7 @@ class JoinCollector {
                 .build()
         }
 
+    @Deprecated("Please use: and(leftColumn) equalTo rightColumn")
     fun and(column: BasicColumn, condition: JoinCondition): JoinCollector =
         apply {
             andJoinCriteria.add(
@@ -47,3 +68,7 @@ class JoinCollector {
             )
         }
 }
+
+class RightColumnCollector(private val joinConditionConsumer: (JoinCondition) -> Unit) {
+    infix fun equalTo(rightColumn: BasicColumn) = joinConditionConsumer.invoke(SqlBuilder.equalTo(rightColumn))
+}
diff --git a/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/elements/SqlElements.kt b/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/elements/SqlElements.kt
index 91b3f6b09..251fc0d71 100644
--- a/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/elements/SqlElements.kt
+++ b/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/elements/SqlElements.kt
@@ -76,6 +76,7 @@ import org.mybatis.dynamic.sql.where.condition.IsNotNull
 import org.mybatis.dynamic.sql.where.condition.IsNull
 
 // join support
+@Deprecated("Please use the infix function in the JoinCollector")
 fun equalTo(column: BasicColumn): EqualTo = SqlBuilder.equalTo(column)
 
 // aggregate support
diff --git a/src/test/kotlin/examples/kotlin/mybatis3/canonical/PersonWithAddressMapperExtensions.kt b/src/test/kotlin/examples/kotlin/mybatis3/canonical/PersonWithAddressMapperExtensions.kt
index ed1f383f1..07cbdda54 100644
--- a/src/test/kotlin/examples/kotlin/mybatis3/canonical/PersonWithAddressMapperExtensions.kt
+++ b/src/test/kotlin/examples/kotlin/mybatis3/canonical/PersonWithAddressMapperExtensions.kt
@@ -24,7 +24,6 @@ import examples.kotlin.mybatis3.canonical.PersonDynamicSqlSupport.id
 import examples.kotlin.mybatis3.canonical.PersonDynamicSqlSupport.lastName
 import examples.kotlin.mybatis3.canonical.PersonDynamicSqlSupport.occupation
 import org.mybatis.dynamic.sql.util.kotlin.SelectCompleter
-import org.mybatis.dynamic.sql.util.kotlin.elements.equalTo
 import org.mybatis.dynamic.sql.util.kotlin.mybatis3.select
 import org.mybatis.dynamic.sql.util.kotlin.mybatis3.selectDistinct
 
@@ -36,7 +35,7 @@ fun PersonWithAddressMapper.selectOne(completer: SelectCompleter): PersonWithAdd
     select(columnList) {
         from(person)
         fullJoin(address) {
-            on(person.addressId, equalTo(address.id))
+            on(person.addressId) equalTo address.id
         }
         completer()
     }.run(this::selectOne)
@@ -45,7 +44,7 @@ fun PersonWithAddressMapper.select(completer: SelectCompleter): List<PersonWithA
     select(columnList) {
         from(person, "p")
         fullJoin(address) {
-            on(person.addressId, equalTo(address.id))
+            on(person.addressId) equalTo address.id
         }
         completer()
     }.run(this::selectMany)
@@ -54,7 +53,7 @@ fun PersonWithAddressMapper.selectDistinct(completer: SelectCompleter): List<Per
     selectDistinct(columnList) {
         from(person)
         fullJoin(address) {
-            on(person.addressId, equalTo(address.id))
+            on(person.addressId) equalTo address.id
         }
         completer()
     }.run(this::selectMany)
diff --git a/src/test/kotlin/examples/kotlin/mybatis3/general/GeneralKotlinTest.kt b/src/test/kotlin/examples/kotlin/mybatis3/general/GeneralKotlinTest.kt
index 350910544..cc3c9dde8 100644
--- a/src/test/kotlin/examples/kotlin/mybatis3/general/GeneralKotlinTest.kt
+++ b/src/test/kotlin/examples/kotlin/mybatis3/general/GeneralKotlinTest.kt
@@ -42,7 +42,6 @@ import org.assertj.core.api.Assertions.assertThat
 import org.assertj.core.api.Assertions.assertThatExceptionOfType
 import org.junit.jupiter.api.Test
 import org.mybatis.dynamic.sql.util.kotlin.elements.count
-import org.mybatis.dynamic.sql.util.kotlin.elements.equalTo
 import org.mybatis.dynamic.sql.util.kotlin.elements.insert
 import org.mybatis.dynamic.sql.util.kotlin.elements.insertMultiple
 import org.mybatis.dynamic.sql.util.kotlin.mybatis3.count
@@ -453,7 +452,7 @@ class GeneralKotlinTest {
             ) {
                 from(person)
                 join(address) {
-                    on(addressId, equalTo(address.id))
+                    on(addressId) equalTo address.id
                 }
                 where { id isLessThan 4 }
                 orderBy(id)
@@ -489,7 +488,7 @@ class GeneralKotlinTest {
             ) {
                 from(person)
                 join(address) {
-                    on(addressId, equalTo(address.id))
+                    on(addressId) equalTo address.id
                 }
                 where { id isLessThan 5 }
                 and {
@@ -530,7 +529,7 @@ class GeneralKotlinTest {
             ) {
                 from(person)
                 join(address) {
-                    on(addressId, equalTo(address.id))
+                    on(addressId) equalTo address.id
                 }
                 where { id isEqualTo 5 }
                 or {
diff --git a/src/test/kotlin/examples/kotlin/mybatis3/joins/JoinMapperTest.kt b/src/test/kotlin/examples/kotlin/mybatis3/joins/JoinMapperTest.kt
index 4dd02acee..5aceb1687 100644
--- a/src/test/kotlin/examples/kotlin/mybatis3/joins/JoinMapperTest.kt
+++ b/src/test/kotlin/examples/kotlin/mybatis3/joins/JoinMapperTest.kt
@@ -65,7 +65,7 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderDetail, "od") {
-                    on(orderMaster.orderId, equalTo(orderDetail.orderId))
+                    on(orderMaster.orderId) equalTo orderDetail.orderId
                 }
             }
 
@@ -102,8 +102,8 @@ class JoinMapperTest {
         ) {
             from(orderMaster, "om")
             join(orderDetail, "od") {
-                on(orderMaster.orderId, equalTo(orderDetail.orderId))
-                and(orderMaster.orderId, equalTo(orderDetail.orderId))
+                on(orderMaster.orderId) equalTo orderDetail.orderId
+                and(orderMaster.orderId) equalTo orderDetail.orderId
             }
         }
 
@@ -121,8 +121,8 @@ class JoinMapperTest {
         ) {
             from(orderMaster, "om")
             join(orderDetail, "od") {
-                on(orderMaster.orderId, equalTo(orderDetail.orderId))
-                and(orderMaster.orderId, equalTo(orderDetail.orderId))
+                on(orderMaster.orderId) equalTo orderDetail.orderId
+                and(orderMaster.orderId) equalTo orderDetail.orderId
             }
             where { orderMaster.orderId isEqualTo 1 }
         }
@@ -133,6 +133,27 @@ class JoinMapperTest {
         assertThat(selectStatement.selectStatement).isEqualTo(expectedStatement)
     }
 
+    @Test
+    fun testDeprecatedJoin() {
+        // this is a nonsensical join, but it does test the "and" capability
+        val selectStatement = select(
+            orderMaster.orderId, orderMaster.orderDate, orderDetail.lineNumber,
+            orderDetail.description, orderDetail.quantity
+        ) {
+            from(orderMaster, "om")
+            join(orderDetail, "od") {
+                on(orderMaster.orderId, equalTo(orderDetail.orderId))
+                and(orderMaster.orderId, equalTo(orderDetail.orderId))
+            }
+            where { orderMaster.orderId isEqualTo 1 }
+        }
+
+        val expectedStatement = "select om.order_id, om.order_date, od.line_number, od.description, od.quantity" +
+                " from OrderMaster om join OrderDetail od on om.order_id = od.order_id and om.order_id = od.order_id" +
+                " where om.order_id = #{parameters.p1,jdbcType=INTEGER}"
+        assertThat(selectStatement.selectStatement).isEqualTo(expectedStatement)
+    }
+
     @Test
     fun testMultipleTableJoinWithWhereClause() {
         newSession().use { session ->
@@ -144,10 +165,10 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 join(itemMaster, "im") {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId))
+                    on(orderLine.itemId) equalTo itemMaster.itemId
                 }
                 where { orderMaster.orderId isEqualTo 2 }
             }
@@ -180,10 +201,10 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 fullJoin(itemMaster, "im") {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId))
+                    on(orderLine.itemId) equalTo itemMaster.itemId
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -255,10 +276,8 @@ class JoinMapperTest {
                         + "ol"
                     },
                     joinCriteria = {
-                        on(
-                            orderMaster.orderId.qualifiedWith("om"),
-                            equalTo(orderLine.orderId.qualifiedWith("ol"))
-                        )
+                        on(orderMaster.orderId.qualifiedWith("om")) equalTo
+                                orderLine.orderId.qualifiedWith("ol")
                     }
                 )
                 fullJoin(
@@ -269,10 +288,8 @@ class JoinMapperTest {
                         + "im"
                     }
                 ) {
-                    on(
-                        orderLine.itemId.qualifiedWith("ol"),
-                        equalTo(itemMaster.itemId.qualifiedWith("im"))
-                    )
+                    on(orderLine.itemId.qualifiedWith("ol")) equalTo
+                            itemMaster.itemId.qualifiedWith("im")
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -331,10 +348,10 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 fullJoin(itemMaster) {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId))
+                    on(orderLine.itemId) equalTo itemMaster.itemId
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -379,10 +396,10 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 leftJoin(itemMaster, "im") {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId))
+                    on(orderLine.itemId) equalTo itemMaster.itemId
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -423,7 +440,7 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 leftJoin(
                     {
@@ -433,7 +450,7 @@ class JoinMapperTest {
                         + "im"
                     }
                 ) {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId.qualifiedWith("im")))
+                    on(orderLine.itemId) equalTo itemMaster.itemId.qualifiedWith("im")
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -473,10 +490,10 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 leftJoin(itemMaster) {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId))
+                    on(orderLine.itemId)  equalTo itemMaster.itemId
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -516,10 +533,10 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 rightJoin(itemMaster, "im") {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId))
+                    on(orderLine.itemId) equalTo itemMaster.itemId
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -560,7 +577,7 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 rightJoin(
                     {
@@ -570,7 +587,7 @@ class JoinMapperTest {
                         + "im"
                     }
                 ) {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId.qualifiedWith("im")))
+                    on(orderLine.itemId) equalTo itemMaster.itemId.qualifiedWith("im")
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -610,10 +627,10 @@ class JoinMapperTest {
             ) {
                 from(orderMaster, "om")
                 join(orderLine, "ol") {
-                    on(orderMaster.orderId, equalTo(orderLine.orderId))
+                    on(orderMaster.orderId) equalTo orderLine.orderId
                 }
                 rightJoin(itemMaster) {
-                    on(orderLine.itemId, equalTo(itemMaster.itemId))
+                    on(orderLine.itemId) equalTo itemMaster.itemId
                 }
                 orderBy(orderLine.orderId, itemMaster.itemId)
             }
@@ -655,7 +672,7 @@ class JoinMapperTest {
             val selectStatement = select(user.userId, user.userName, user.parentId) {
                 from(user, "u1")
                 join(user2, "u2") {
-                    on(user.userId, equalTo(user2.parentId))
+                    on(user.userId) equalTo user2.parentId
                 }
                 where { user2.userId isEqualTo 4 }
             }
@@ -686,7 +703,7 @@ class JoinMapperTest {
             val selectStatement = select(user.userId, user.userName, user.parentId) {
                 from(user)
                 join(user2) {
-                    on(user.userId, equalTo(user2.parentId))
+                    on(user.userId) equalTo user2.parentId
                 }
                 where { user2.userId isEqualTo 4 }
             }
@@ -718,7 +735,7 @@ class JoinMapperTest {
             val selectStatement = select(user.userId, user.userName, user.parentId) {
                 from(user, "u1")
                 join(user2, "u2") {
-                    on(user.userId, equalTo(user2.parentId))
+                    on(user.userId) equalTo user2.parentId
                 }
                 where { user2.userId isEqualTo 4 }
             }
diff --git a/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTemplateDirectTest.kt b/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTemplateDirectTest.kt
index 610327a7d..2c85b90b9 100644
--- a/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTemplateDirectTest.kt
+++ b/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTemplateDirectTest.kt
@@ -29,7 +29,6 @@ import org.assertj.core.api.Assertions.assertThat
 import org.junit.jupiter.api.Test
 import org.mybatis.dynamic.sql.util.kotlin.elements.add
 import org.mybatis.dynamic.sql.util.kotlin.elements.constant
-import org.mybatis.dynamic.sql.util.kotlin.elements.equalTo
 import org.mybatis.dynamic.sql.util.kotlin.spring.count
 import org.mybatis.dynamic.sql.util.kotlin.spring.countDistinct
 import org.mybatis.dynamic.sql.util.kotlin.spring.countFrom
@@ -524,7 +523,7 @@ open class CanonicalSpringKotlinTemplateDirectTest {
         ) {
             from(person, "p")
             join(address, "a") {
-                on(addressId, equalTo(address.id))
+                on(addressId) equalTo address.id
             }
             where { id isLessThan 4 }
             orderBy(id)
diff --git a/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTest.kt b/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTest.kt
index da728470f..f9f048d1b 100644
--- a/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTest.kt
+++ b/src/test/kotlin/examples/kotlin/spring/canonical/CanonicalSpringKotlinTest.kt
@@ -30,7 +30,6 @@ import org.assertj.core.api.Assertions.assertThatExceptionOfType
 import org.junit.jupiter.api.Test
 import org.mybatis.dynamic.sql.util.kotlin.elements.add
 import org.mybatis.dynamic.sql.util.kotlin.elements.constant
-import org.mybatis.dynamic.sql.util.kotlin.elements.equalTo
 import org.mybatis.dynamic.sql.util.kotlin.elements.insert
 import org.mybatis.dynamic.sql.util.kotlin.elements.insertBatch
 import org.mybatis.dynamic.sql.util.kotlin.elements.insertMultiple
@@ -854,7 +853,7 @@ open class CanonicalSpringKotlinTest {
         ) {
             from(person, "p")
             join(address, "a") {
-                on(addressId, equalTo(address.id))
+                on(addressId) equalTo address.id
             }
             where { id isLessThan 4 }
             orderBy(id)

From c55db90d2aef8a3e713d6e1cee18e5a1146465d4 Mon Sep 17 00:00:00 2001
From: Jeff Butler <jeffgbutler@gmail.com>
Date: Mon, 7 Feb 2022 08:57:05 -0500
Subject: [PATCH 2/4] Merge fixes

---
 .../kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt  | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt b/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt
index f13449666..20bff932c 100644
--- a/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt
+++ b/src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/JoinCollector.kt
@@ -16,6 +16,7 @@
 package org.mybatis.dynamic.sql.util.kotlin
 
 import org.mybatis.dynamic.sql.BasicColumn
+import org.mybatis.dynamic.sql.SqlBuilder
 import org.mybatis.dynamic.sql.select.join.JoinCondition
 import org.mybatis.dynamic.sql.select.join.JoinCriterion
 

From 35f8117b055556fc16ff98729554e1924c051c7b Mon Sep 17 00:00:00 2001
From: Jeff Butler <jeffgbutler@gmail.com>
Date: Mon, 7 Feb 2022 09:30:11 -0500
Subject: [PATCH 3/4] Join documentation updates

---
 CHANGELOG.md                             | 14 ++++++-----
 src/site/markdown/docs/kotlinMyBatis3.md |  2 +-
 src/site/markdown/docs/kotlinOverview.md | 32 ++++++++++++++++--------
 3 files changed, 30 insertions(+), 18 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c0d8f13c7..d1dd25ece 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,17 +20,19 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
    ([#438](https://github.com/mybatis/mybatis-dynamic-sql/pull/438))
 4. Major update to the Kotlin where clause DSL. Where clauses now support the "group" and "not" features from above. In
    addition, the where clause DSL has been fully updated to make it feel more like natural SQL. The previous version
-   of the where clause DSL yielded almost unreadable code when the "group" and "not" functions were added. This update
-   is better all around and yields a DSL that is very similar to native SQL. The new DSL includes many Kotlin DSL
-   construction features including infix functions, operator overloads, and functions with receivers. We believe it
-   will be well worth the effort to migrate to the new DSL. The prior where clause DSL remains in the library for now,
-   but is deprecated. It will be removed in version 1.5.0 of the library. Documentation for the new DSL is here:
-   https://github.com/mybatis/mybatis-dynamic-sql/blob/master/src/site/markdown/docs/kotlinWhereClauses.md
+   of the where clause DSL would have yielded almost unreadable code had the "group" and "not" functions been added.
+   This update is better all around and yields a DSL that is very similar to native SQL. The new DSL includes many
+   Kotlin DSL construction features including infix functions, operator overloads, and functions with receivers.
+   We believe it will be well worth the effort to migrate to the new DSL. The prior where clause DSL remains in the
+   library for now, but is deprecated. It will be removed in version 1.5.0 of the library. Documentation for the new
+   DSL is here: https://github.com/mybatis/mybatis-dynamic-sql/blob/master/src/site/markdown/docs/kotlinWhereClauses.md
    ([#442](https://github.com/mybatis/mybatis-dynamic-sql/pull/442))
 5. General cleanup of the Kotlin DSL. The Kotlin DSL functions are now mostly Unit functions. This should have
    no impact on most users and is source code compatible with prior versions of the library when the library was used
    as described in the documentation. This change greatly simplifies the type hierarchy of the Kotlin builders.
    ([#446](https://github.com/mybatis/mybatis-dynamic-sql/pull/446))
+6. Minor update the Kotlin join DSL to make it closer to natural SQL. The existing join methods are deprecated and
+   will be removed in version 1.5.0.
 
 ## Release 1.3.1 - December 18, 2021
 
diff --git a/src/site/markdown/docs/kotlinMyBatis3.md b/src/site/markdown/docs/kotlinMyBatis3.md
index b08e0d2a4..171104de0 100644
--- a/src/site/markdown/docs/kotlinMyBatis3.md
+++ b/src/site/markdown/docs/kotlinMyBatis3.md
@@ -922,7 +922,7 @@ fun PersonWithAddressMapper.select(completer: SelectCompleter): List<PersonWithA
     ) {
         from(person, "p")
         fullJoin(address) {
-            on(person.addressId, equalTo(address.id))
+            on(person.addressId) equalTo address.id
         }
         completer()
     }.run(this::selectMany)
diff --git a/src/site/markdown/docs/kotlinOverview.md b/src/site/markdown/docs/kotlinOverview.md
index 6e18d4abc..4b1d287c1 100644
--- a/src/site/markdown/docs/kotlinOverview.md
+++ b/src/site/markdown/docs/kotlinOverview.md
@@ -396,25 +396,35 @@ This method creates models or providers depending on which package is used:
 Select statement support enables the creation of methods that execute a query allowing a user to specify a where clause,
 join specifications, order by clauses, group by clauses, pagination clauses, etc.
 
-The DSL for select statements looks like this:
+The full DSL for select statements looks like this:
 
 ```kotlin
-val selectStatement = select(id, firstName, lastName, birthDate, employed, occupation, addressId) {
-   from(person)
-   where { id isLessThan 5 }
-   and {
-      id isLessThan 4
-      and {
-         id isLessThan 3
-         or { id isLessThan 2 }
-      }
+val selectStatement = select(orderMaster.orderId, orderMaster.orderDate, orderDetail.lineNumber,
+   orderDetail.description, orderDetail.quantity
+) {
+   from(orderMaster, "om")
+   join(orderDetail, "od") {
+      on(orderMaster.orderId) equalTo orderDetail.orderId
+      and(orderMaster.orderId) equalTo orderDetail.orderId
    }
-   orderBy(id)
+   where { orderMaster.orderId isEqualTo 1 }
+   or {
+      orderMaster.orderId isEqualTo 2
+      and { orderDetail.quantity isLessThan 6 }
+   }
+   orderBy(orderMaster.orderId)
    limit(3)
 }
 ```
 
+In a select statement you must specify a table in a `from` clause. Everything else is optional.
+
+Multiple join clauses can be specified if you need to join additional tables. In a join clause, you must
+specify an `on` condition, and you may specify additional `and` conditions as necessary. Full, left, right, inner,
+and outer joins are supported.
+
 Where clauses can be of arbitrary complexity and support all SQL operators including exists operators, subqueries, etc.
+You can nest `and`, `or`, and `not` clauses as necessary in where clauses.
 
 There is also a method that will create a "distinct" query (`select distinct ...`) as follows:
 

From 5fddb3f70785f6c3df6793ca9127115a035b2a63 Mon Sep 17 00:00:00 2001
From: Jeff Butler <jeffgbutler@gmail.com>
Date: Mon, 7 Feb 2022 11:10:23 -0500
Subject: [PATCH 4/4] Add PR to CHANGELOG.md

---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index d1dd25ece..ac0bb470a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -32,7 +32,7 @@ GitHub milestone: [https://github.com/mybatis/mybatis-dynamic-sql/issues?q=miles
    as described in the documentation. This change greatly simplifies the type hierarchy of the Kotlin builders.
    ([#446](https://github.com/mybatis/mybatis-dynamic-sql/pull/446))
 6. Minor update the Kotlin join DSL to make it closer to natural SQL. The existing join methods are deprecated and
-   will be removed in version 1.5.0.
+   will be removed in version 1.5.0. ([#447](https://github.com/mybatis/mybatis-dynamic-sql/pull/447))
 
 ## Release 1.3.1 - December 18, 2021