src/share/classes/java/util/function/BinaryOperator.java

rev 7675 : 8019840: Spec updates for java.util.function
Reviewed-by: mduigou
Contributed-by: brian.goetz@oracle.com

@@ -26,45 +26,51 @@
 
 import java.util.Objects;
 import java.util.Comparator;
 
 /**
- * An operation upon two operands yielding a result. This is a specialization of
- * {@code BiFunction} where the operands and the result are all of the same type.
+ * Represents an operation upon two operands of the same type, producing a result
+ * of the same type as the operands.  This is a specialization of
+ * {@link BiFunction} for the case where the operands and the result are all of
+ * the same type.
  *
- * @param <T> the type of operands to {@code apply} and of the result
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(Object, Object)}.
+ *
+ * @param <T> the type of the operands and result of the operator
  *
  * @see BiFunction
+ * @see UnaryOperator
  * @since 1.8
  */
 @FunctionalInterface
 public interface BinaryOperator<T> extends BiFunction<T,T,T> {
     /**
      * Returns a {@link BinaryOperator} which returns the lesser of two elements
-     * according to the specified {@code Comparator}
+     * according to the specified {@code Comparator}.
      *
-     * @param <T> the type of values to be compared and returned
+     * @param <T> the type of the input arguments of the comparator
      * @param  comparator a {@code Comparator} for comparing the two values
      * @return a {@code BinaryOperator} which returns the lesser of its operands,
      *         according to the supplied {@code Comparator}
      * @throws NullPointerException if the argument is null
      */
-    public static<T> BinaryOperator<T> minBy(Comparator<? super T> comparator) {
+    public static <T> BinaryOperator<T> minBy(Comparator<? super T> comparator) {
         Objects.requireNonNull(comparator);
         return (a, b) -> comparator.compare(a, b) <= 0 ? a : b;
     }
 
     /**
      * Returns a {@link BinaryOperator} which returns the greater of two elements
-     * according to the specified {@code Comparator}
+     * according to the specified {@code Comparator}.
      *
-     * @param <T> the type of values to be compared and returned
+     * @param <T> the type of the input arguments of the comparator
      * @param  comparator a {@code Comparator} for comparing the two values
      * @return a {@code BinaryOperator} which returns the greater of its operands,
      *         according to the supplied {@code Comparator}
      * @throws NullPointerException if the argument is null
      */
-    public static<T> BinaryOperator<T> maxBy(Comparator<? super T> comparator) {
+    public static <T> BinaryOperator<T> maxBy(Comparator<? super T> comparator) {
         Objects.requireNonNull(comparator);
         return (a, b) -> comparator.compare(a, b) >= 0 ? a : b;
     }
 }