Docs

Author: jeffgbutler

src/site/markdown/docs/migratingV1toV2.md

@@ -1,45 +1,21 @@
 # V1 to V2 Migration Guide
 
-Version 2 of MyBatis Dynamic SQL introduced many new features. This page will document how to migrate code
-from prior releases to version 2.
+Version 2 of MyBatis Dynamic SQL introduced many new features. On this page we will provide examples for the more
+significant changes - changes that are more substantial than following deprecation messages.
 
-## Java Join Syntax
-
-Version2 offers a fully flexible join specification and reuses the capabilities of where clauses. Of course,
-not all capabilities are supported in databases, but you should now be able to code any type of join specification.
+## Kotlin Join Syntax
 
+The Java DSL for joins was changed to allow much more flexible joins. Of course, not all capabilities are supported in
+all databases, but you should now be able to code most joins specification that are supported by your database.
 The changes in the Java DSL are mostly internal and should not impact most users. The `equalTo` methods has been
 deprecated in favor of `isEqualTo`, but all other changes should be hidden.
 
-V1 Join Specification Example:
-```java
-SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDetail.lineNumber, orderDetail.quantity)
-        .from(orderMaster, "om")
-        .join(orderDetail, "od", on(orderMaster.orderId, equalTo(orderDetail.orderId)))
-        .build()
-        .render(RenderingStrategies.MYBATIS3);
-```
+Like the Java DSL, the V2 Kotlin DSL offers a fully flexible join specification and allows for much more flexible join
+specifications. The changes in the Kotlin DSL allow a more natural expressions of a join specification. The main 
+difference is that the "on" keyword should be moved outside the join specification lambda (it is now an infix function).
+Inside the lambda, the conditions should be rewritten to match the syntax of a where clause.
 
-V2 Join Specification Example:
-```java
-SelectStatementProvider selectStatement = select(orderMaster.orderId, orderDetail.lineNumber, orderDetail.quantity)
-        .from(orderMaster, "om")
-        .join(orderDetail, "od", on(orderMaster.orderId, isEqualTo(orderDetail.orderId)))
-        .build()
-        .render(RenderingStrategies.MYBATIS3);
-```
-
-## Kotlin Join Syntax
-
-Like the Java DSL, the V2 Kotlin DSL offers a fully flexible join specification and reuses the capabilities of where
-clauses. Of course, not all capabilities are supported in databases, but you should now be able to code any type of
-join specification.
-
-The changes in the Kotlin DSL allow a more natural expressions of a join specification. The main difference is that
-the "on" keyword should be moved outside the join specification lambda (it is now an infix function). Inside the lambda,
-the conditions should be rewritten to match the syntax of a where clause.
-
-V1 Join Specification Example:
+V1 (Deprecated) Join Specification Example:
 ```kotlin
 val selectStatement = select(
     orderMaster.orderId, orderMaster.orderDate,
@@ -65,5 +41,9 @@ val selectStatement = select(
         and { orderMaster.orderId isEqualTo constant("1") }
     }
 }
-
 ```
+
+Notice that the "on" keyword has been moved outside the lambda, and the conditions are coded with the same syntax used
+by WHERE, HAVING, and CASE expressions.
+
+The prior syntax is deprecated and will be removed in a future release.