Update and add documentation (#1059)

* Fix, tests

 JAVA-4799

Author: katcharov

driver-core/src/main/com/mongodb/client/model/expressions/ArrayExpression.java

@@ -21,35 +21,39 @@
 import static com.mongodb.client.model.expressions.Expressions.of;
 
 /**
- * Expresses an array value. An array value is a finite, ordered collection of
- * elements of a certain type.
+ * An array {@link Expression value} in the context of the MongoDB Query
+ * Language (MQL). An array is a finite, ordered collection of elements of a
+ * certain type. It is also known as a finite mathematical sequence.
  *
- * @param <T> the type of the elements in the array
+ * @param <T> the type of the elements
  */
 public interface ArrayExpression<T extends Expression> extends Expression {
 
     /**
-     * Returns an array consisting of those elements in this array that match
-     * the given predicate condition. Evaluates each expression in this array
-     * according to the cond function. If cond evaluates to logical true, then
-     * the element is preserved; if cond evaluates to logical false, the element
-     * is omitted.
+     * An array consisting of only those elements in {@code this} array that
+     * match the provided predicate.
      *
-     * @param cond the function to apply to each element
-     * @return the new array
+     * @param predicate the predicate to apply to each element to determine if
+     *                  it should be included.
+     * @return the resulting array.
      */
-    ArrayExpression<T> filter(Function<? super T, ? extends BooleanExpression> cond);
+    ArrayExpression<T> filter(Function<? super T, ? extends BooleanExpression> predicate);
 
     /**
-     * Returns an array consisting of the results of applying the given function
-     * to the elements of this array.
+     * An array consisting of the results of applying the provided function to
+     * the elements of {@code this} array.
      *
-     * @param in the function to apply to each element
-     * @return the new array
-     * @param <R> the type contained in the resulting array
+     * @param in the function to apply to each element.
+     * @return the resulting array.
+     * @param <R> the type of the elements of the resulting array.
      */
     <R extends Expression> ArrayExpression<R> map(Function<? super T, ? extends R> in);
 
+    /**
+     * The size of {@code this} array.
+     *
+     * @return the size.
+     */
     IntegerExpression size();
 
     BooleanExpression any(Function<? super T, BooleanExpression> predicate);
@@ -113,7 +117,25 @@ default ArrayExpression<T> slice(final int start, final int length) {
 
     ArrayExpression<T> distinct();
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passArrayTo(Function<? super ArrayExpression<T>, ? extends R> f);
 
-    <R extends Expression> R switchArrayOn(Function<Branches<ArrayExpression<T>>, ? extends BranchesTerminal<ArrayExpression<T>, ? extends R>> on);
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchArrayOn(Function<Branches<ArrayExpression<T>>, ? extends BranchesTerminal<ArrayExpression<T>, ? extends R>> mapping);
 }

driver-core/src/main/com/mongodb/client/model/expressions/BooleanExpression.java

@@ -19,7 +19,8 @@
 import java.util.function.Function;
 
 /**
- * A logical boolean value, either true or false.
+ * A boolean {@linkplain Expression value} in the context of the
+ * MongoDB Query Language (MQL).
  */
 public interface BooleanExpression extends Expression {
 
@@ -45,20 +46,37 @@ public interface BooleanExpression extends Expression {
      * @return the resulting value.
      */
     BooleanExpression and(BooleanExpression other);
-    // TODO-END check the evaluation semantics of and/or
 
     /**
-     * The {@code left} branch when {@code this} is true,
-     * and the {@code right} branch otherwise.
+     * The {@code ifTrue} value when {@code this} is true,
+     * and the {@code ifFalse} value otherwise.
      *
-     * @param left the left branch.
-     * @param right the right branch.
+     * @param ifTrue the ifTrue value.
+     * @param ifFalse the ifFalse value.
      * @return the resulting value.
      * @param <T> The type of the resulting expression.
      */
-    <T extends Expression> T cond(T left, T right);
+    <T extends Expression> T cond(T ifTrue, T ifFalse);
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passBooleanTo(Function<? super BooleanExpression, ? extends R> f);
 
-    <R extends Expression> R switchBooleanOn(Function<Branches<BooleanExpression>, ? extends BranchesTerminal<BooleanExpression, ? extends R>> on);
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchBooleanOn(Function<Branches<BooleanExpression>, ? extends BranchesTerminal<BooleanExpression, ? extends R>> mapping);
 }

driver-core/src/main/com/mongodb/client/model/expressions/DateExpression.java

@@ -19,8 +19,11 @@
 import java.util.function.Function;
 
 /**
- * An instantaneous date and time. Tracks a UTC datetime, the number of
- * milliseconds since the Unix epoch. Does not track the timezone.
+ * A UTC date-time {@linkplain Expression value} in the context
+ * of the MongoDB Query Language (MQL). Tracks the number of
+ * milliseconds since the Unix epoch, and does not track the timezone.
+ *
+ * @mongodb.driver.manual reference/operator/aggregation/dateToString/ Format Specifiers, UTC Offset, and Olson Timezone Identifier
  */
 public interface DateExpression extends Expression {
 
@@ -123,11 +126,30 @@ public interface DateExpression extends Expression {
      * provided {@code timezone}, and formatted according to the {@code format}.
      *
      * @param timezone the UTC Offset or Olson Timezone Identifier.
-     * @param format the format specifier. TODO-END what standard is this?
+     * @param format the format specifier.
      * @return the resulting value.
      */
     StringExpression asString(StringExpression timezone, StringExpression format);
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passDateTo(Function<? super DateExpression, ? extends R> f);
-    <R extends Expression> R switchDateOn(Function<Branches<DateExpression>, ? extends BranchesTerminal<DateExpression, ? extends R>> on);
+
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchDateOn(Function<Branches<DateExpression>, ? extends BranchesTerminal<DateExpression, ? extends R>> mapping);
 }

driver-core/src/main/com/mongodb/client/model/expressions/DocumentExpression.java

@@ -102,6 +102,25 @@ default <T extends Expression> MapExpression<T> getMap(final String fieldName, f
 
     MapExpression<Expression> asMap();
 
+    /**
+     * The result of passing {@code this} value to the provided function.
+     * Equivalent to {@code f.apply(this)}, and allows lambdas and static,
+     * user-defined functions to use the chaining syntax.
+     *
+     * @see Expression#passTo
+     * @param f the function to apply.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
     <R extends Expression> R passDocumentTo(Function<? super DocumentExpression, ? extends R> f);
-    <R extends Expression> R switchDocumentOn(Function<Branches<DocumentExpression>, ? extends BranchesTerminal<DocumentExpression, ? extends R>> on);
+
+    /**
+     * The result of applying the provided switch mapping to {@code this} value.
+     *
+     * @see Expression#switchOn
+     * @param mapping the switch mapping.
+     * @return the resulting value.
+     * @param <R> the type of the resulting value.
+     */
+    <R extends Expression> R switchDocumentOn(Function<Branches<DocumentExpression>, ? extends BranchesTerminal<DocumentExpression, ? extends R>> mapping);
 }

driver-core/src/main/com/mongodb/client/model/expressions/EntryExpression.java

@@ -18,6 +18,19 @@
 
 import static com.mongodb.client.model.expressions.Expressions.of;
 
+/**
+ * A map entry {@linkplain Expression value} in the context
+ * of the MongoDB Query Language (MQL). An entry has a
+ * {@linkplain StringExpression string} key and some
+ * {@linkplain Expression value}. Entries are used with
+ * {@linkplain MapExpression maps}.
+ *
+ * Entries are {@linkplain Expression#isDocumentOr document-like} and
+ * {@linkplain Expression#isMapOr map-like}, unless the method returning the
+ * entry specifies otherwise.
+ *
+ * @param <T> The type of the value
+ */
 public interface EntryExpression<T extends Expression> extends Expression {
     StringExpression getKey();