Javadoc for expressions

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

@@ -19,37 +19,43 @@
 import java.util.function.Function;
 
 import static com.mongodb.client.model.expressions.Expressions.of;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.PRESENT;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.NON_EMPTY;
 
 /**
- * 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);
@@ -81,6 +87,7 @@ public interface ArrayExpression<T extends Expression> extends Expression {
      * @param i
      * @return
      */
+    @MqlUnchecked(PRESENT)
     T elementAt(IntegerExpression i);
 
     default T elementAt(final int i) {
@@ -91,6 +98,7 @@ default T elementAt(final int i) {
      * user asserts that array is not empty
      * @return
      */
+    @MqlUnchecked(NON_EMPTY)
     T first();
 
     /**
@@ -113,7 +121,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,49 +19,64 @@
 import java.util.function.Function;
 
 /**
- * Expresses a boolean value.
+ * A boolean {@linkplain Expression value} in the context of the
+ * MongoDB Query Language (MQL).
  */
 public interface BooleanExpression extends Expression {
 
     /**
-     * Returns logical true if this expression evaluates to logical false.
-     * Returns logical false if this expression evaluates to logical true.
+     * The logical negation of {@code this} value.
      *
-     * @return True if false; false if true.
+     * @return the resulting value.
      */
     BooleanExpression not();
 
     /**
-     * Returns logical true if this or the other expression evaluates to logical
-     * true. Returns logical false if both evaluate to logical false.
+     * The logical conjunction of {@code this} and the {@code other} value.
      *
-     * @param or the other boolean expression.
-     * @return True if either true, false if both false.
+     * @param other the other boolean value.
+     * @return the resulting value.
      */
-    BooleanExpression or(BooleanExpression or);
+    BooleanExpression or(BooleanExpression other);
 
     /**
-     * Returns logical true if both this and the other expression evaluate to
-     * logical true. Returns logical false if either evaluate to logical false.
+     * The logical disjunction of {@code this} and the {@code other} value.
      *
-     * @param and the other boolean expression.
-     * @return true if both true, false if either false.
+     * @param other the other boolean value.
+     * @return the resulting value.
      */
-    BooleanExpression and(BooleanExpression and);
+    BooleanExpression and(BooleanExpression other);
 
     /**
-     * If this expression evaluates to logical true, returns the result of the
-     * evaluated left branch expression. If this evaluates to logical false,
-     * returns the result of the evaluated right branch expression.
+     * The {@code ifTrue} value when {@code this} is true,
+     * and the {@code ifFalse} value otherwise.
      *
-     * @param left the left branch expression
-     * @param right the right branch expression
-     * @return left if true, right if false.
+     * @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/Branches.java

@@ -20,6 +20,8 @@
 import java.util.List;
 import java.util.function.Function;
 
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.TYPE_ARGUMENT;
+
 public final class Branches<T extends Expression> {
 
     Branches() {
@@ -78,7 +80,7 @@ public <R extends Expression> BranchesIntermediary<T, R> isDate(final Function<?
     }
 
     @SuppressWarnings("unchecked")
-    public <R extends Expression, Q extends Expression> BranchesIntermediary<T, R> isArray(final Function<? super ArrayExpression<Q>, ? extends R> r) {
+    public <R extends Expression, Q extends Expression> BranchesIntermediary<T, R> isArray(final Function<? super ArrayExpression<@MqlUnchecked(TYPE_ARGUMENT) Q>, ? extends R> r) {
         return is(v -> mqlEx(v).isArray(), v -> r.apply((ArrayExpression<Q>) v));
     }
 

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

@@ -19,22 +19,137 @@
 import java.util.function.Function;
 
 /**
- * Expresses a date value.
+ * 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 {
+
+    /**
+     * The year of {@code this} date as determined by the provided
+     * {@code timezone}.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression year(StringExpression timezone);
+
+    /**
+     * The month of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 1 and 12.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression month(StringExpression timezone);
+
+    /**
+     * The day of the month of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 1 and 31.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression dayOfMonth(StringExpression timezone);
+
+    /**
+     * The day of the week of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 1 (Sunday) and 7 (Saturday).
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression dayOfWeek(StringExpression timezone);
+
+    /**
+     * The day of the year of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 1 and 366.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression dayOfYear(StringExpression timezone);
+
+    /**
+     * The hour of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 0 and 23.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression hour(StringExpression timezone);
+
+    /**
+     * The minute of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 0 and 59.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression minute(StringExpression timezone);
+
+    /**
+     * The second of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 0 and 59, and 60 in the case
+     * of a leap second.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression second(StringExpression timezone);
+
+    /**
+     * The week of the year of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 0 and 53.
+     *
+     * <p>Weeks begin on Sundays, and week 1 begins with the first Sunday of the
+     * year. Days preceding the first Sunday of the year are in week 0.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression week(StringExpression timezone);
+
+    /**
+     * The millisecond part of {@code this} date as determined by the provided
+     * {@code timezone}, as an integer between 0 and 999.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @return the resulting value.
+     */
     IntegerExpression millisecond(StringExpression timezone);
 
+    /**
+     * The string representation of {@code this} date as determined by the
+     * provided {@code timezone}, and formatted according to the {@code format}.
+     *
+     * @param timezone the UTC Offset or Olson Timezone Identifier.
+     * @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

@@ -23,6 +23,8 @@
 
 import static com.mongodb.client.model.expressions.Expressions.of;
 import static com.mongodb.client.model.expressions.Expressions.ofMap;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.PRESENT;
+import static com.mongodb.client.model.expressions.MqlUnchecked.Unchecked.TYPE;
 
 /**
  * Expresses a document value. A document is an ordered set of fields, where the
@@ -34,8 +36,10 @@ public interface DocumentExpression extends Expression {
 
     DocumentExpression unsetField(String fieldName);
 
+    @MqlUnchecked(PRESENT)
     Expression getField(String fieldName);
 
+    @MqlUnchecked({PRESENT, TYPE})
     BooleanExpression getBoolean(String fieldName);
 
     BooleanExpression getBoolean(String fieldName, BooleanExpression other);
@@ -102,6 +106,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);
 }