Documentation polishing

Author: jeffgbutler

src/main/kotlin/org/mybatis/dynamic/sql/util/kotlin/GroupingCriteriaCollector.kt

@@ -33,13 +33,13 @@ typealias GroupingCriteriaReceiver = GroupingCriteriaCollector.() -> Unit
  * an initial criterion, and sub-criteria connected by either an "and" or an "or".
  *
  * An initial criterion can be one of four types:
- * - A column and condition (called with the invoke operator on a column)
+ * - A column and condition (called with the invoke operator on a column, or an infix function)
  * - An exists operator (called with the "exists" function)
- * - A criteria group which is essentially parenthesis within the where clause (called with the group function)
- * - A "not" group (called with the not function)
+ * - A criteria group which is essentially parenthesis within the where clause (called with the "group" function)
+ * - A criteria group preceded with "not" (called with the "not" function)
  *
- * Only one of these initial criterion functions should be called within each scope. If you need more than one,
- * use a sub-criteria joined with "and" or "or"
+ * Only one of the initial criterion functions should be called within each scope. If you need more than one,
+ * use a sub-criterion joined with "and" or "or"
  */
 @Suppress("TooManyFunctions")
 @MyBatisDslMarker
@@ -54,6 +54,14 @@ class GroupingCriteriaCollector {
 
     internal val subCriteria = mutableListOf<AndOrCriteriaGroup>()
 
+    /**
+     * Add sub criterion joined with "and" to the current context. If the receiver adds more than one
+     * criterion that renders at runtime then parenthesis will be added.
+     *
+     * This function may be called multiple times in a context.
+     *
+     * @param criteriaReceiver a function to create the contained criteria
+     */
     fun and(criteriaReceiver: GroupingCriteriaReceiver): Unit =
         with(GroupingCriteriaCollector().apply(criteriaReceiver)) {
             this@GroupingCriteriaCollector.subCriteria.add(
@@ -64,6 +72,14 @@ class GroupingCriteriaCollector {
             )
         }
 
+    /**
+     * Add sub criterion joined with "or" to the current context. If the receiver adds more than one
+     * criterion that renders at runtime then parenthesis will be added.
+     *
+     * This function may be called multiple times in a context.
+     *
+     * @param criteriaReceiver a function to create the contained criteria
+     */
     fun or(criteriaReceiver: GroupingCriteriaReceiver): Unit =
         with(GroupingCriteriaCollector().apply(criteriaReceiver)) {
             this@GroupingCriteriaCollector.subCriteria.add(
@@ -75,7 +91,13 @@ class GroupingCriteriaCollector {
         }
 
     /**
-     * This should only be specified once per scope, and should be first
+     * Add an initial criterion preceded with "not" to the current context. If the receiver adds more than one
+     * criterion that renders at runtime then parenthesis will be added.
+     *
+     * This may only be called once per scope, and cannot be combined with "exists", "group", "invoke",
+     * or any infix function in the same scope.
+     *
+     * @param criteriaReceiver a function to create the contained criteria
      */
     fun not(criteriaReceiver: GroupingCriteriaReceiver): Unit =
         with(GroupingCriteriaCollector().apply(criteriaReceiver)) {
@@ -86,7 +108,12 @@ class GroupingCriteriaCollector {
         }
 
     /**
-     * This should only be specified once per scope, and should be first
+     * Add an initial criterion composed of a sub-query preceded with "exists" to the current context.
+     *
+     * This should only be specified once per scope, and cannot be combined with "invoke",
+     * "group", "not", or any infix function in the same scope.
+     *
+     * @param kotlinSubQueryBuilder a function to create a select statement
      */
     fun exists(kotlinSubQueryBuilder: KotlinSubQueryBuilder.() -> Unit): Unit =
         with(KotlinSubQueryBuilder().apply(kotlinSubQueryBuilder)) {
@@ -95,11 +122,17 @@ class GroupingCriteriaCollector {
         }
 
     /**
+     * Add an initial criterion to the current context. If the receiver adds more than one
+     * criterion that renders at runtime then parenthesis will be added.
+     *
+     * This should only be specified once per scope, and cannot be combined with "exists", "invoke",
+     * "not", or any infix function in the same scope.
+     *
      * This could "almost" be an operator invoke function. The problem is that
-     * to call it a user would need to use "this" explicitly. I think that is too
+     * to call it a user would need to use "this" explicitly. We think that is too
      * confusing, so we'll stick with the function name of "group"
      *
-     * This should only be specified once per scope, and should be first
+     * @param criteriaReceiver a function to create the contained criteria
      */
     fun group(criteriaReceiver: GroupingCriteriaReceiver): Unit =
         with(GroupingCriteriaCollector().apply(criteriaReceiver)) {
@@ -110,8 +143,16 @@ class GroupingCriteriaCollector {
         }
 
     /**
-     * Build an initial criterion for a where clause, or a nested and/or/not group.
-     * You can use it like A (isEqualTo(3))
+     * Add an initial criterion to the current context based on a column and condition.
+     * You can use it like "A.invoke(isEqualTo(3))" or "A (isEqualTo(3))".
+     *
+     * This is an extension function to a BindableColumn, but is scoped to the context of the
+     * current collector.
+     *
+     * This should only be specified once per scope, and cannot be combined with "exists", "group",
+     * "not", or any infix function in the same scope.
+     *
+     * @param condition the condition to be applied to this column, in this scope
      */
     operator fun <T> BindableColumn<T>.invoke(condition: VisitableCondition<T>) {
         initialCriterion = ColumnAndConditionCriterion.withColumn(this)

src/site/markdown/docs/kotlinWhereClauses.md

@@ -6,7 +6,7 @@ overload functions, infix functions, and Kotlin receiver functions.
 
 ## Simple Where Clauses
 
-The simplest form of where clause includes a single condition. An example follows:
+The simplest form of where clause includes a single condition. See the following examples:
 
 ```kotlin
 select(foo) {
@@ -36,8 +36,8 @@ select(foo) {
 ```
 
 Most, but not all, of the built-in conditions can be expressed as infix functions. Conditions without parameters,
-or varargs conditions, cannot be called with infix. Good examples of those conditions are `isNull` and `isIn`. In
-those cases you will need to call the function directly as follows:
+or varargs conditions, cannot be called as an infix function. Good examples of conditions that cannot be called via
+an infix function are `isNull` and `isIn`. In those cases you will need to call the function directly as follows:
 
 ```kotlin
 select(foo) {
@@ -56,30 +56,30 @@ select(foo) {
 Many conditions support `filter` and `map` functions that can be used to test whether the condition should be rendered
 or to change the value of the condition parameter(s). If you need to use the `filter` or `map` functions, then you
 cannot use the infix functions. In this case you can use a function that creates the condition and then apply
-that condition to the where clause. For example:
+that condition to the where clause via the invoke operator. For example:
 
 ```kotlin
 select(foo) {
     from(bar)
-    where { id (isEqualTo(3).map { it + 2 }) }
+    where { firstName (isLike("fred").map { "%$it%" }) } // add wildcards for like
 }
 ```
 
-In this case, `isEqualTo` is a function in the `org.mybatis.dynamic.sql.util.kotlin.elements` package, not the infix
-function. Note that the condition is enclosed in parentheses. This is actually a function call using a Kotlin invoke
-operator overload. This can also be called explicitly without the operator overload as follows:
+In this case, `isLike` is a function in the `org.mybatis.dynamic.sql.util.kotlin.elements` package, not the infix
+function. Note also that the condition is enclosed in parentheses. This is actually a function call using a Kotlin
+invoke operator overload. This can also be called explicitly without the operator overload as follows:
 
 ```kotlin
 select(foo) {
     from(bar)
-    where { id.invoke(isEqualTo(3).map { it + 2 }) }
+    where { firstName.invoke(isLike("fred").map { "%$it%" }) } // add wildcards for like
 }
 ```
 
 ## Compound Where Clauses
 
 Of course many where clauses are composed of more than one condition. The where DSL supports arbitrarily complex
-where clauses with and/or/not phrases.
+where clauses with and/or/not phrases. See the following example of a complex where clause:
 
 ```kotlin
 select(foo) {
@@ -94,8 +94,9 @@ select(foo) {
 ```
 
 The `and`, `or`, and `not` functions each create a new context that can in turn include `and`, `or`, and `not`
-functions. The DSL has no limit on the depth of nesting of these functions. When there are nested `and` and `or`
-functions, the curly braces will essentially be rendered as parentheses in the final SQL.
+functions. The DSL has no practical limit on the depth of nesting of these functions. When there are nested
+`and` and `or` functions, the curly braces will be rendered as parentheses in the final SQL if the context contains
+more than one condition.
 
 ## Initial and Subsequent Conditions
 
@@ -110,19 +111,21 @@ Everything is optional - if you don't specify an initial condition, or any subse
 render.
 
 For each context, the renderer will add parenthesis around the rendered context if there is more than one condition in
-the context. Remember that the `filter` function can be used to remove a condition from rendering, so the parentheses
-are added only if the enclosed conditions all render.
+the context. Remember that a `filter` function can be used to remove some conditions from rendering, so the
+parentheses are added only if there is more than one condition that renders.
 
-If you forget to specify an initial condition and only specify `and` and `or` groups, then the first "and" or "or"
-will be removed during rendering. This to avoid a rendered where clause like "where and id = 3".
+If you neglect to specify an initial condition and only specify `and` and `or` groups, then the first "and" or "or"
+will be removed during rendering. This to avoid a rendered where clause like "where and id = 3". This can be useful
+in situations where a where clause is composed by a number of different functions - there is no need to keep track
+of who goes first as the renderer will automatically strip the first connector.
 
 ### Initial Condition Types
 
 There are four types of initial conditions. Only one of the initial condition types may be specified in any
 given context. Others must be enclosed in an `and` or an `or` block. The four types are as follows:
 
-1. **Column and Criterion** (`id isEqualTo 3` - as shown above)
-2. **Not** (`not { id isEqualTo 3 }` - as shown above)
+1. **Column and Criterion** - either with the infix functions, or the invoke function as shown above
+2. **Not** - appends "not" to a group of criteria or a single criterion as shown above
 3. **Exists** - for executing an exists sub-query:
 
     ```kotlin
@@ -173,11 +176,11 @@ given context. Others must be enclosed in an `and` or an `or` block. The four ty
 
 ## Extending Where Clauses
 
-In addition to the built-in conditions supplied with the library, it is possible to write your own custom
-conditions. Any custom condition can be used with the "invoke operator" method shown above in the "Using Filter And Map"
-section above.
+In addition to the built-in conditions supplied with the library, it is also possible to write your own custom
+conditions. Any custom condition can be used with the "invoke operator" method shown above in the
+"Using Filter And Map" section above.
 
 At this time, it is not possible to add infix functions for custom conditions to the library. This is due to an
 underlying limitation in Kotlin itself. There is a Kotlin language enhancement on the roadmap that will likely
-remove this limitation. The enhancement will allow multiple receivers for an extension function. You can follow
+remove this limitation. That enhancement will allow multiple receivers for an extension function. You can follow
 progress of that enhancement here: https://youtrack.jetbrains.com/issue/KT-42435