Join documentation updates

Author: jeffgbutler

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
 

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)

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: