Add javadoc for boolean, date, number, integer, and expression (#1059)

 JAVA-4799

Author: katcharov

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

@@ -19,44 +19,41 @@
 import java.util.function.Function;
 
 /**
- * Expresses a boolean value.
+ * A logical boolean value, either true or false.
  */
 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);
+    // TODO-END check the evaluation semantics of and/or
 
     /**
-     * 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 left} branch when {@code this} is true,
+     * and the {@code right} branch otherwise.
      *
-     * @param left the left branch expression
-     * @param right the right branch expression
-     * @return left if true, right if false.
+     * @param left the left branch.
+     * @param right the right branch.
+     * @return the resulting value.
      * @param <T> The type of the resulting expression.
      */
     <T extends Expression> T cond(T left, T right);

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

@@ -19,20 +19,113 @@
 import java.util.function.Function;
 
 /**
- * Expresses a date value.
+ * An instantaneous date and time. Tracks a UTC datetime, the number of
+ * milliseconds since the Unix epoch. Does not track the timezone.
  */
 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. TODO-END what standard is this?
+     * @return the resulting value.
+     */
     StringExpression asString(StringExpression timezone, StringExpression format);
 
     <R extends Expression> R passDateTo(Function<? super DateExpression, ? extends R> f);