8019840: Spec updates for java.util.function

Reviewed-by: mduigou, chegar
Contributed-by: brian.goetz@oracle.com

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

@@ -27,13 +27,16 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation which accepts two input arguments and returns no result. This is
- * the two-arity specialization of {@link Consumer}. Unlike most other
- * functional interfaces, {@code BiConsumer} is expected to operate via
- * side-effects.
+ * Represents an operation that accepts two input arguments and returns no
+ * result.  This is the two-arity specialization of {@link Consumer}.
+ * Unlike most other functional interfaces, {@code BiConsumer} is expected
+ * to operate via side-effects.
  *
- * @param <T> the type of the first argument to the {@code accept} operation
- * @param <U> the type of the second argument to the {@code accept} operation
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the operation
+ * @param <U> the type of the second argument to the operation
  *
  * @see Consumer
  * @since 1.8
@@ -42,35 +45,31 @@ import java.util.Objects;
 public interface BiConsumer<T, U> {
 
     /**
-     * Performs operations upon the provided objects which may modify those
-     * objects and/or external state.
+     * Performs this operation on the given arguments.
      *
-     * @param t an input object
-     * @param u an input object
+     * @param t the first input argument
+     * @param u the second input argument
      */
     void accept(T t, U u);
 
     /**
-     * Returns a {@code BiConsumer} which performs, in sequence, the operation
-     * represented by this object followed by the operation represented by
-     * the other {@code BiConsumer}.
-     *
-     * <p>Any exceptions thrown by either {@code accept} method are relayed
-     * to the caller; if performing this operation throws an exception, the
-     * other operation will not be performed.
+     * Returns a composed {@code BiConsumer} that performs, in sequence, this
+     * operation followed by the {@code after} operation. If performing either
+     * operation throws an exception, it is relayed to the caller of the
+     * composed operation.  If performing this operation throws an exception,
+     * the {@code after} operation will not be performed.
      *
-     * @param other a BiConsumer which will be chained after this BiConsumer
-     * @return a BiConsumer which performs in sequence the {@code accept} method
-     * of this BiConsumer and the {@code accept} method of the specified
-     * BiConsumer operation
-     * @throws NullPointerException if other is null
+     * @param after the operation to perform after this operation
+     * @return a composed {@code BiConsumer} that performs in sequence this
+     * operation followed by the {@code after} operation
+     * @throws NullPointerException if {@code after} is null
      */
-    default BiConsumer<T, U> chain(BiConsumer<? super T, ? super U> other) {
-        Objects.requireNonNull(other);
+    default BiConsumer<T, U> andThen(BiConsumer<? super T, ? super U> after) {
+        Objects.requireNonNull(after);
 
         return (l, r) -> {
             accept(l, r);
-            other.accept(l, r);
+            after.accept(l, r);
         };
     }
 }

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

@@ -27,14 +27,15 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * Apply a function to the input arguments, yielding an appropriate result. This
- * is the two-arity specialization of {@link Function}. A function may
- * variously provide a mapping between types, object instances or keys and
- * values or any other form of transformation upon the input.
+ * Represents a function that accepts two arguments and produces a result.
+ * This is the two-arity specialization of {@link Function}.
  *
- * @param <T> the type of the first argument to the {@code apply} operation
- * @param <U> the type of the second argument to the {@code apply} operation
- * @param <R> the type of results returned by the {@code apply} operation
+ * <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 first argument to the function
+ * @param <U> the type of the second argument to the function
+ * @param <R> the type of the result of the function
  *
  * @see Function
  * @since 1.8
@@ -43,25 +44,25 @@ import java.util.Objects;
 public interface BiFunction<T, U, R> {
 
     /**
-     * Compute the result of applying the function to the input arguments
+     * Applies this function to the given arguments.
      *
-     * @param t an input object
-     * @param u an input object
+     * @param t the first function argument
+     * @param u the second function argument
      * @return the function result
      */
     R apply(T t, U u);
 
     /**
-     * Returns a new function which applies this function followed by the
-     * provided function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed function that first applies this function to
+     * its input, and then applies the {@code after} function to the result.
+     * If evaluation of either function throws an exception, it is relayed to
+     * the caller of the composed function.
      *
-     * @param <V> Type of output objects to the combined function. May be the
-     * same type as {@code <T>}, {@code <U>} or {@code <R>}
-     * @param after An additional function to be applied after this function is
-     * applied
-     * @return A function which performs this function followed by the provided
-     * function
+     * @param <V> the type of output of the {@code after} function, and of the
+     *           composed function
+     * @param after the function to apply after this function is applied
+     * @return a composed function that first applies this function and then
+     * applies the {@code after} function
      * @throws NullPointerException if after is null
      */
     default <V> BiFunction<T, U, V> andThen(Function<? super R, ? extends V> after) {

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

@@ -27,11 +27,14 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * Determines if the input objects match some criteria. This is the two-arity
- * specialization of {@link Predicate}.
+ * Represents a predicate (boolean-valued function) of two arguments.  This is
+ * the two-arity specialization of {@link Predicate}.
  *
- * @param <T> the type of the first argument to {@code test}
- * @param <U> the type of the second argument to {@code test}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #test(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the predicate
+ * @param <U> the type of the second argument the predicate
  *
  * @see Predicate
  * @since 1.8
@@ -40,34 +43,41 @@ import java.util.Objects;
 public interface BiPredicate<T, U> {
 
     /**
-     * Return {@code true} if the inputs match some criteria.
+     * Evaluates this predicate on the given arguments.
      *
-     * @param t an input object
-     * @param u an input object
-     * @return {@code true} if the inputs match some criteria
+     * @param t the first input argument
+     * @param u the second input argument
+     * @return {@code true} if the input arguments match the predicate,
+     * otherwise {@code false}
      */
     boolean test(T t, U u);
 
     /**
-     * Returns a predicate which evaluates to {@code true} only if this
-     * predicate and the provided predicate both evaluate to {@code true}. If
-     * this predicate returns {@code false} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * AND of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code false}, then the {@code other}
+     * predicate is not evaluated.
+     *
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ANDed with this predicate
-     * @return a new predicate which returns {@code true} only if both
-     * predicates return {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ANDed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * AND of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default BiPredicate<T, U> and(BiPredicate<? super T, ? super U> p) {
-        Objects.requireNonNull(p);
-        return (T t, U u) -> test(t, u) && p.test(t, u);
+    default BiPredicate<T, U> and(BiPredicate<? super T, ? super U> other) {
+        Objects.requireNonNull(other);
+        return (T t, U u) -> test(t, u) && other.test(t, u);
     }
 
     /**
-     * Returns a predicate which negates the result of this predicate.
+     * Returns a predicate that represents the logical negation of this
+     * predicate.
      *
-     * @return a new predicate who's result is always the opposite of this
+     * @return a predicate that represents the logical negation of this
      * predicate
      */
     default BiPredicate<T, U> negate() {
@@ -75,18 +85,23 @@ public interface BiPredicate<T, U> {
     }
 
     /**
-     * Returns a predicate which evaluates to {@code true} if either this
-     * predicate or the provided predicate evaluates to {@code true}. If this
-     * predicate returns {@code true} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * OR of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code true}, then the {@code other}
+     * predicate is not evaluated.
+     *
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ORed with this predicate
-     * @return a new predicate which returns {@code true} if either predicate
-     * returns {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ORed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * OR of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default BiPredicate<T, U> or(BiPredicate<? super T, ? super U> p) {
-        Objects.requireNonNull(p);
-        return (T t, U u) -> test(t, u) || p.test(t, u);
+    default BiPredicate<T, U> or(BiPredicate<? super T, ? super U> other) {
+        Objects.requireNonNull(other);
+        return (T t, U u) -> test(t, u) || other.test(t, u);
     }
 }

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

@@ -28,42 +28,48 @@ 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  comparator a {@code Comparator} for comparing the two values
+     * @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  comparator a {@code Comparator} for comparing the two values
+     * @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;
     }

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

@@ -26,8 +26,14 @@ package java.util.function;
 
 
 /**
- * A supplier of {@code boolean} values. This is the {@code boolean}-providing
- * primitive specialization of {@link Supplier}.
+ * Represents a supplier of {@code boolean}-valued results.  This is the
+ * {@code boolean}-producing primitive specialization of {@link Supplier}.
+ *
+ * <p>There is no requirement that a new or distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #getAsBoolean()}.
  *
  * @see Supplier
  * @since 1.8
@@ -36,9 +42,9 @@ package java.util.function;
 public interface BooleanSupplier {
 
     /**
-     * Returns a {@code boolean} value.
+     * Gets a result.
      *
-     * @return a {@code boolean} value
+     * @return a result
      */
     boolean getAsBoolean();
 }

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

@@ -27,11 +27,14 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation which accepts a single input argument and returns no result.
- * Unlike most other functional interfaces, {@code Consumer} is expected to
- * operate via side-effects.
+ * Represents an operation that accepts a single input argument and returns no
+ * result. Unlike most other functional interfaces, {@code Consumer} is expected
+ * to operate via side-effects.
  *
- * @param <T> The type of input objects to {@code accept}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object)}.
+ *
+ * @param <T> the type of the input to the operation
  *
  * @since 1.8
  */
@@ -39,29 +42,26 @@ import java.util.Objects;
 public interface Consumer<T> {
 
     /**
-     * Accept an input value.
+     * Performs this operation on the given argument.
      *
-     * @param t the input object
+     * @param t the input argument
      */
     void accept(T t);
 
     /**
-     * Returns a {@code Consumer} which performs, in sequence, the operation
-     * represented by this object followed by the operation represented by
-     * the other {@code Consumer}.
-     *
-     * <p>Any exceptions thrown by either {@code accept} method are relayed
-     * to the caller; if performing this operation throws an exception, the
-     * other operation will not be performed.
+     * Returns a composed {@code Consumer} that performs, in sequence, this
+     * operation followed by the {@code after} operation. If performing either
+     * operation throws an exception, it is relayed to the caller of the
+     * composed operation.  If performing this operation throws an exception,
+     * the {@code after} operation will not be performed.
      *
-     * @param other a Consumer which will be chained after this Consumer
-     * @return a Consumer which performs in sequence the {@code accept} method
-     * of this Consumer and the {@code accept} method of the specified Consumer
-     * operation
-     * @throws NullPointerException if other is null
+     * @param after the operation to perform after this operation
+     * @return a composed {@code Consumer} that performs in sequence this
+     * operation followed by the {@code after} operation
+     * @throws NullPointerException if {@code after} is null
      */
-    default Consumer<T> chain(Consumer<? super T> other) {
-        Objects.requireNonNull(other);
-        return (T t) -> { accept(t); other.accept(t); };
+    default Consumer<T> andThen(Consumer<? super T> after) {
+        Objects.requireNonNull(after);
+        return (T t) -> { accept(t); after.accept(t); };
     }
 }

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

@@ -25,23 +25,25 @@
 package java.util.function;
 
 /**
- * An operation on two {@code double} operands yielding a {@code double} result.
- * This is the primitive type specialization of {@link BinaryOperator} for
- * {@code double}.
+ * Represents an operation upon two {@code double}-valued operands and producing a
+ * {@code double}-valued result.   This is the primitive type specialization of
+ * {@link BinaryOperator} for {@code double}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(double, double)}.
  *
  * @see BinaryOperator
+ * @see DoubleUnaryOperator
  * @since 1.8
  */
 @FunctionalInterface
 public interface DoubleBinaryOperator {
     /**
-     * Returns the {@code double} result of the operation upon the
-     * {@code double} operands. The parameters are named {@code left} and
-     * {@code right} for operations where the order of parameters matters.
+     * Applies this operator to the given operands.
      *
-     * @param left the left operand value
-     * @param right the right operand value
-     * @return the result of the operation
+     * @param left the first operand
+     * @param right the second operand
+     * @return the operator result
      */
     double applyAsDouble(double left, double right);
 }

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

@@ -27,11 +27,14 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation which accepts a single double argument and returns no result.
- * This is the primitive type specialization of {@link Consumer} for
- * {@code double}. Unlike most other functional interfaces,
+ * Represents an operation that accepts a single {@code double}-valued argument and
+ * returns no result.  This is the primitive type specialization of
+ * {@link Consumer} for {@code double}.  Unlike most other functional interfaces,
  * {@code DoubleConsumer} is expected to operate via side-effects.
  *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(double)}.
+ *
  * @see Consumer
  * @since 1.8
  */
@@ -39,30 +42,26 @@ import java.util.Objects;
 public interface DoubleConsumer {
 
     /**
-     * Accept an input value.
+     * Performs this operation on the given argument.
      *
-     * @param value the input value
+     * @param value the input argument
      */
     void accept(double value);
 
     /**
-     * Returns a {@code DoubleConsumer} which performs, in sequence, the operation
-     * represented by this object followed by the operation represented by
-     * another {@code DoubleConsumer}.
-     *
-     * <p>Any exceptions thrown by either {@code accept} method are relayed
-     * to the caller; if performing this operation throws an exception, the
-     * other operation will not be performed.
+     * Returns a composed {@code DoubleConsumer} that performs, in sequence, this
+     * operation followed by the {@code after} operation. If performing either
+     * operation throws an exception, it is relayed to the caller of the
+     * composed operation.  If performing this operation throws an exception,
+     * the {@code after} operation will not be performed.
      *
-     * @param other a DoubleConsumer which will be chained after this
-     * DoubleConsumer
-     * @return an DoubleConsumer which performs in sequence the {@code accept} method
-     * of this DoubleConsumer and the {@code accept} method of the specified IntConsumer
-     * operation
-     * @throws NullPointerException if other is null
+     * @param after the operation to perform after this operation
+     * @return a composed {@code DoubleConsumer} that performs in sequence this
+     * operation followed by the {@code after} operation
+     * @throws NullPointerException if {@code after} is null
      */
-    default DoubleConsumer chain(DoubleConsumer other) {
-        Objects.requireNonNull(other);
-        return (double t) -> { accept(t); other.accept(t); };
+    default DoubleConsumer andThen(DoubleConsumer after) {
+        Objects.requireNonNull(after);
+        return (double t) -> { accept(t); after.accept(t); };
     }
 }

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

@@ -25,11 +25,14 @@
 package java.util.function;
 
 /**
- * Apply a function to the double-valued input argument, yielding an appropriate
- * result. This is the {@code double}-consuming primitive specialization for
+ * Represents a function that accepts a double-valued argument and produces a
+ * result.  This is the {@code double}-consuming primitive specialization for
  * {@link Function}.
  *
- * @param <R> the type of output objects from the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(double)}.
+ *
+ * @param <R> the type of the result of the function
  *
  * @see Function
  * @since 1.8
@@ -38,9 +41,9 @@ package java.util.function;
 public interface DoubleFunction<R> {
 
     /**
-     * Compute the result of applying the function to the input argument
+     * Applies this function to the given argument.
      *
-     * @param value the input value
+     * @param value the function argument
      * @return the function result
      */
     R apply(double value);

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

@@ -27,9 +27,12 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * Determines if the {@code double} input value matches some criteria. This is
- * the {@code double}-consuming primitive type specialization of
- * {@link Predicate}.
+ * Represents a predicate (boolean-valued function) of one {@code double}-valued
+ * argument. This is the {@code double}-consuming primitive type specialization
+ * of {@link Predicate}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #test(double)}.
  *
  * @see Predicate
  * @since 1.8
@@ -38,38 +41,40 @@ import java.util.Objects;
 public interface DoublePredicate {
 
     /**
-     * Returns {@code true} if the input value matches some criteria.
+     * Evaluates this predicate on the given argument.
      *
-     * @param value the value to be tested
-     * @return {@code true} if the input value matches some criteria, otherwise
-     * {@code false}
+     * @param value the input argument
+     * @return {@code true} if the input argument matches the predicate,
+     * otherwise {@code false}
      */
     boolean test(double value);
 
     /**
-     * Returns a predicate which evaluates to {@code true} only if this
-     * predicate and the provided predicate both evaluate to {@code true}. If
-     * this predicate returns {@code false} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * AND of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code false}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ANDed with this predicate
-     * @return a new predicate which returns {@code true} only if both
-     * predicates return {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ANDed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * AND of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default DoublePredicate and(DoublePredicate p) {
-        Objects.requireNonNull(p);
-        return (value) -> test(value) && p.test(value);
+    default DoublePredicate and(DoublePredicate other) {
+        Objects.requireNonNull(other);
+        return (value) -> test(value) && other.test(value);
     }
 
     /**
-     * Returns a predicate which negates the result of this predicate.
+     * Returns a predicate that represents the logical negation of this
+     * predicate.
      *
-     * @return a new predicate who's result is always the opposite of this
+     * @return a predicate that represents the logical negation of this
      * predicate
      */
     default DoublePredicate negate() {
@@ -77,22 +82,23 @@ public interface DoublePredicate {
     }
 
     /**
-     * Returns a predicate which evaluates to {@code true} if either this
-     * predicate or the provided predicate evaluates to {@code true}. If this
-     * predicate returns {@code true} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * OR of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code true}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ANDed with this predicate
-     * @return a new predicate which returns {@code true} if either predicate
-     * returns {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ORed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * OR of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default DoublePredicate or(DoublePredicate p) {
-        Objects.requireNonNull(p);
-        return (value) -> test(value) || p.test(value);
+    default DoublePredicate or(DoublePredicate other) {
+        Objects.requireNonNull(other);
+        return (value) -> test(value) || other.test(value);
     }
 }

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

@@ -25,8 +25,14 @@
 package java.util.function;
 
 /**
- * A supplier of {@code double} values. This is the {@code double}-providing
- * primitive specialization of {@link Supplier}.
+ * Represents a supplier of {@code double}-valued results.  This is the
+ * {@code double}-producing primitive specialization of {@link Supplier}.
+ *
+ * <p>There is no requirement that a distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #getAsDouble()}.
  *
  * @see Supplier
  * @since 1.8
@@ -35,9 +41,9 @@ package java.util.function;
 public interface DoubleSupplier {
 
     /**
-     * Returns a {@code double} value.
+     * Gets a result.
      *
-     * @return a {@code double} value
+     * @return a result
      */
     double getAsDouble();
 }

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

@@ -25,22 +25,24 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code double}-to-{@code int} specialization for {@link Function}.
+ * Represents a function that accepts a double-valued argument and produces an
+ * int-valued result.  This is the {@code double}-to-{@code int} primitive
+ * specialization for {@link Function}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(double)}.
  *
  * @see Function
- * @see IntToDoubleFunction
- * @see LongToIntFunction
  * @since 1.8
  */
 @FunctionalInterface
 public interface DoubleToIntFunction {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given argument.
      *
-     * @param value the input value
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
     int applyAsInt(double value);
 }

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

@@ -25,22 +25,24 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code double}-to-{@code long} specialization for {@link Function}.
+ * Represents a function that accepts a double-valued argument and produces a
+ * long-valued result.  This is the {@code double}-to-{@code long} primitive
+ * specialization for {@link Function}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(double)}.
  *
  * @see Function
- * @see LongToDoubleFunction
- * @see IntToLongFunction
  * @since 1.8
  */
 @FunctionalInterface
 public interface DoubleToLongFunction {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given argument.
      *
-     * @param value the input value
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
     long applyAsLong(double value);
 }

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

@@ -27,9 +27,12 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation on a {@code double} operand yielding a {@code double}
- * result. This is the primitive type specialization of {@link UnaryOperator}
- * for {@code double}.
+ * Represents an operation on a single {@code double}-valued operand that produces
+ * a {@code double}-valued result.  This is the primitive type specialization of
+ * {@link UnaryOperator} for {@code double}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(double)}.
  *
  * @see UnaryOperator
  * @since 1.8
@@ -38,24 +41,25 @@ import java.util.Objects;
 public interface DoubleUnaryOperator {
 
     /**
-     * Returns the {@code double} result of the operation upon the
-     * {@code double} operand.
+     * Applies this operator to the given operand.
      *
-     * @param operand the operand value
-     * @return the operation result value
+     * @param operand the operand
+     * @return the operator result
      */
     double applyAsDouble(double operand);
 
     /**
-     * Compose a new function which applies the provided function followed by
-     * this function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed operator that first applies the {@code before}
+     * operator to its input, and then applies this operator to the result.
+     * If evaluation of either operator throws an exception, it is relayed to
+     * the caller of the composed operator.
      *
-     * @param before An additional function to be applied before this function
-     * is applied
-     * @return A function which performs the provided function followed by this
-     * function
+     * @param before the operator to apply before this operator is applied
+     * @return a composed operator that first applies the {@code before}
+     * operator and then applies this operator
      * @throws NullPointerException if before is null
+     *
+     * @see #andThen(DoubleUnaryOperator)
      */
     default DoubleUnaryOperator compose(DoubleUnaryOperator before) {
         Objects.requireNonNull(before);
@@ -63,15 +67,17 @@ public interface DoubleUnaryOperator {
     }
 
     /**
-     * Compose a new function which applies this function followed by the
-     * provided function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed operator that first applies this operator to
+     * its input, and then applies the {@code after} operator to the result.
+     * If evaluation of either operator throws an exception, it is relayed to
+     * the caller of the composed operator.
      *
-     * @param after An additional function to be applied after this function is
-     * applied
-     * @return A function which performs this function followed by the provided
-     * function followed
+     * @param after the operator to apply after this operator is applied
+     * @return a composed operator that first applies this operator and then
+     * applies the {@code after} operator
      * @throws NullPointerException if after is null
+     *
+     * @see #compose(DoubleUnaryOperator)
      */
     default DoubleUnaryOperator andThen(DoubleUnaryOperator after) {
         Objects.requireNonNull(after);
@@ -79,9 +85,9 @@ public interface DoubleUnaryOperator {
     }
 
     /**
-     * Returns a unary operator that provides its input value as the result.
+     * Returns a unary operator that always returns its input argument.
      *
-     * @return a unary operator that provides its input value as the result
+     * @return a unary operator that always returns its input argument
      */
     static DoubleUnaryOperator identity() {
         return t -> t;

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

@@ -27,12 +27,13 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.  A
- * function may variously provide a mapping between types, object instances or
- * keys and values or any other form of transformation upon the input.
+ * Represents a function that accepts one argument and produces a result.
  *
- * @param <T> the type of the input to the {@code apply} operation
- * @param <R> the type of the result of the {@code apply} operation
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(Object)}.
+ *
+ * @param <T> the type of the input to the function
+ * @param <R> the type of the result of the function
  *
  * @since 1.8
  */
@@ -40,25 +41,27 @@ import java.util.Objects;
 public interface Function<T, R> {
 
     /**
-     * Compute the result of applying the function to the input argument
+     * Applies this function to the given argument.
      *
-     * @param t the input object
+     * @param t the function argument
      * @return the function result
      */
     R apply(T t);
 
     /**
-     * Returns a new function which applies the provided function followed by
-     * this function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed function that first applies the {@code before}
+     * function to its input, and then applies this function to the result.
+     * If evaluation of either function throws an exception, it is relayed to
+     * the caller of the composed function.
      *
-     * @param <V> type of input objects to the combined function. May be the
-     * same type as {@code <T>} or {@code <R>}
-     * @param before an additional function to be applied before this function
-     * is applied
-     * @return a function which performs the provided function followed by this
-     * function
+     * @param <V> the type of input to the {@code before} function, and to the
+     *           composed function
+     * @param before the function to apply before this function is applied
+     * @return a composed function that first applies the {@code before}
+     * function and then applies this function
      * @throws NullPointerException if before is null
+     *
+     * @see #andThen(Function)
      */
     default <V> Function<V, R> compose(Function<? super V, ? extends T> before) {
         Objects.requireNonNull(before);
@@ -66,17 +69,19 @@ public interface Function<T, R> {
     }
 
     /**
-     * Returns a new function which applies this function followed by the
-     * provided function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed function that first applies this function to
+     * its input, and then applies the {@code after} function to the result.
+     * If evaluation of either function throws an exception, it is relayed to
+     * the caller of the composed function.
      *
-     * @param <V> type of output objects to the combined function. May be the
-     * same type as {@code <T>} or {@code <R>}
-     * @param after an additional function to be applied after this function is
-     * applied
-     * @return a function which performs this function followed by the provided
-     * function
+     * @param <V> the type of output of the {@code after} function, and of the
+     *           composed function
+     * @param after the function to apply after this function is applied
+     * @return a composed function that first applies this function and then
+     * applies the {@code after} function
      * @throws NullPointerException if after is null
+     *
+     * @see #compose(Function)
      */
     default <V> Function<T, V> andThen(Function<? super R, ? extends V> after) {
         Objects.requireNonNull(after);
@@ -84,10 +89,10 @@ public interface Function<T, R> {
     }
 
     /**
-     * Returns a {@code Function} whose {@code apply} method returns its input.
+     * Returns a function that always returns its input argument.
      *
      * @param <T> the type of the input and output objects to the function
-     * @return a {@code Function} whose {@code apply} method returns its input
+     * @return a function that always returns its input argument
      */
     static <T> Function<T, T> identity() {
         return t -> t;

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

@@ -25,24 +25,26 @@
 package java.util.function;
 
 /**
- * An operation on two {@code int} operands yielding an {@code int} result.
- * This is the primitive type specialization of {@link BinaryOperator} for
- * {@code int}.
+ * Represents an operation upon two {@code int}-valued operands and producing an
+ * {@code int}-valued result.   This is the primitive type specialization of
+ * {@link BinaryOperator} for {@code int}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(int, int)}.
  *
  * @see BinaryOperator
+ * @see IntUnaryOperator
  * @since 1.8
  */
 @FunctionalInterface
 public interface IntBinaryOperator {
 
     /**
-     * Returns the {@code int} result of the operation upon the {@code int}
-     * operands. The parameters are named {@code left} and {@code right} for
-     * operations where the order of parameters matters.
+     * Applies this operator to the given operands.
      *
-     * @param left the left operand value
-     * @param right  the right operand value
-     * @return the result of the operation
+     * @param left the first operand
+     * @param right the second operand
+     * @return the operator result
      */
     int applyAsInt(int left, int right);
 }

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

@@ -27,10 +27,13 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation which accepts a single integer argument and returns no result.
- * This is the primitive type specialization of {@link Consumer} for {@code int}.
- * Unlike most other functional interfaces, {@code IntConsumer} is expected to
- * operate via side-effects.
+ * Represents an operation that accepts a single {@code int}-valued argument and
+ * returns no result.  This is the primitive type specialization of
+ * {@link Consumer} for {@code int}.  Unlike most other functional interfaces,
+ * {@code IntConsumer} is expected to operate via side-effects.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(int)}.
  *
  * @see Consumer
  * @since 1.8
@@ -39,30 +42,26 @@ import java.util.Objects;
 public interface IntConsumer {
 
     /**
-     * Accept an input value.
+     * Performs this operation on the given argument.
      *
-     * @param value the input value
+     * @param value the input argument
      */
     void accept(int value);
 
     /**
-     * Returns an {@code IntConsumer} which performs, in sequence, the operation
-     * represented by this object followed by the operation represented by
-     * another {@code IntConsumer}.
-     *
-     * <p>Any exceptions thrown by either {@code accept} method are relayed
-     * to the caller; if performing this operation throws an exception, the
-     * other operation will not be performed.
+     * Returns a composed {@code IntConsumer} that performs, in sequence, this
+     * operation followed by the {@code after} operation. If performing either
+     * operation throws an exception, it is relayed to the caller of the
+     * composed operation.  If performing this operation throws an exception,
+     * the {@code after} operation will not be performed.
      *
-     * @param other an IntConsumer which will be chained after this
-     * IntConsumer
-     * @return an IntConsumer which performs in sequence the {@code accept} method
-     * of this IntConsumer and the {@code accept} method of the specified IntConsumer
-     * operation
-     * @throws NullPointerException if other is null
+     * @param after the operation to perform after this operation
+     * @return a composed {@code IntConsumer} that performs in sequence this
+     * operation followed by the {@code after} operation
+     * @throws NullPointerException if {@code after} is null
      */
-    default IntConsumer chain(IntConsumer other) {
-        Objects.requireNonNull(other);
-        return (int t) -> { accept(t); other.accept(t); };
+    default IntConsumer andThen(IntConsumer after) {
+        Objects.requireNonNull(after);
+        return (int t) -> { accept(t); after.accept(t); };
     }
 }

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

@@ -25,11 +25,14 @@
 package java.util.function;
 
 /**
- * Apply a function to the integer-valued input argument, yielding an
- * appropriate result. This is the {@code int}-consuming primitive
- * specialization for {@link Function}.
+ * Represents a function that accepts an int-valued argument and produces a
+ * result.  This is the {@code int}-consuming primitive specialization for
+ * {@link Function}.
  *
- * @param <R> the type of output objects from the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(int)}.
+ *
+ * @param <R> the type of the result of the function
  *
  * @see Function
  * @since 1.8
@@ -38,9 +41,9 @@ package java.util.function;
 public interface IntFunction<R> {
 
     /**
-     * Compute the result of applying the function to the input argument
+     * Applies this function to the given argument.
      *
-     * @param value the input value
+     * @param value the function argument
      * @return the function result
      */
     R apply(int value);

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

@@ -27,8 +27,12 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * Determines if the {@code int} input value matches some criteria. This is the
- * {@code int}-consuming primitive type specialization of {@link Predicate}.
+ * Represents a predicate (boolean-valued function) of one {@code int}-valued
+ * argument. This is the {@code int}-consuming primitive type specialization of
+ * {@link Predicate}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #test(int)}.
  *
  * @see Predicate
  * @since 1.8
@@ -37,38 +41,40 @@ import java.util.Objects;
 public interface IntPredicate {
 
     /**
-     * Returns {@code true} if the input value matches some criteria.
+     * Evaluates this predicate on the given argument.
      *
-     * @param value the value to be tested
-     * @return {@code true} if the input value matches some criteria, otherwise
-     * {@code false}
+     * @param value the input argument
+     * @return {@code true} if the input argument matches the predicate,
+     * otherwise {@code false}
      */
     boolean test(int value);
 
     /**
-     * Returns a predicate which evaluates to {@code true} only if this
-     * predicate and the provided predicate both evaluate to {@code true}. If
-     * this predicate returns {@code false} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * AND of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code false}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ANDed with this predicate
-     * @return a new predicate which returns {@code true} only if both
-     * predicates return {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ANDed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * AND of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default IntPredicate and(IntPredicate p) {
-        Objects.requireNonNull(p);
-        return (value) -> test(value) && p.test(value);
+    default IntPredicate and(IntPredicate other) {
+        Objects.requireNonNull(other);
+        return (value) -> test(value) && other.test(value);
     }
 
     /**
-     * Returns a predicate which negates the result of this predicate.
+     * Returns a predicate that represents the logical negation of this
+     * predicate.
      *
-     * @return a new predicate who's result is always the opposite of this
+     * @return a predicate that represents the logical negation of this
      * predicate
      */
     default IntPredicate negate() {
@@ -76,22 +82,23 @@ public interface IntPredicate {
     }
 
     /**
-     * Returns a predicate which evaluates to {@code true} if either this
-     * predicate or the provided predicate evaluates to {@code true}. If this
-     * predicate returns {@code true} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * OR of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code true}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ORed with this predicate
-     * @return a new predicate which returns {@code true} if either predicate
-     * returns {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ORed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * OR of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default IntPredicate or(IntPredicate p) {
-        Objects.requireNonNull(p);
-        return (value) -> test(value) || p.test(value);
+    default IntPredicate or(IntPredicate other) {
+        Objects.requireNonNull(other);
+        return (value) -> test(value) || other.test(value);
     }
 }

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

@@ -25,8 +25,14 @@
 package java.util.function;
 
 /**
- * A supplier of {@code int} values. This is the {@code int}-providing
- * primitive specialization of {@link Supplier}.
+ * Represents a supplier of {@code int}-valued results.  This is the
+ * {@code int}-producing primitive specialization of {@link Supplier}.
+ *
+ * <p>There is no requirement that a distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #getAsInt()}.
  *
  * @see Supplier
  * @since 1.8
@@ -35,9 +41,9 @@ package java.util.function;
 public interface IntSupplier {
 
     /**
-     * Returns an {@code int} value.
+     * Gets a result.
      *
-     * @return an {@code int} value
+     * @return a result
      */
     int getAsInt();
 }

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

@@ -25,22 +25,24 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code int}-to-{@code double} specialization for {@link Function}.
+ * Represents a function that accepts an int-valued argument and produces a
+ * double-valued result.  This is the {@code int}-to-{@code double} primitive
+ * specialization for {@link Function}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(int)}.
  *
  * @see Function
- * @see DoubleToIntFunction
- * @see LongToDoubleFunction
  * @since 1.8
  */
 @FunctionalInterface
 public interface IntToDoubleFunction {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given argument.
      *
-     * @param value the input value
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
     double applyAsDouble(int value);
 }

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

@@ -25,22 +25,24 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code int}-to-{@code long} specialization for {@link Function}.
+ * Represents a function that accepts an int-valued argument and produces a
+ * long-valued result.  This is the {@code int}-to-{@code long} primitive
+ * specialization for {@link Function}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(int)}.
  *
  * @see Function
- * @see LongToIntFunction
- * @see DoubleToLongFunction
  * @since 1.8
  */
 @FunctionalInterface
 public interface IntToLongFunction {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given argument.
      *
-     * @param value the input value
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
     long applyAsLong(int value);
 }

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

@@ -27,9 +27,12 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation on a single {@code int} operand yielding an {@code int} result.
- * This is the primitive type specialization of {@link UnaryOperator} for
- * {@code int}.
+ * Represents an operation on a single {@code int}-valued operand that produces
+ * an {@code int}-valued result.  This is the primitive type specialization of
+ * {@link UnaryOperator} for {@code int}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(int)}.
  *
  * @see UnaryOperator
  * @since 1.8
@@ -38,24 +41,25 @@ import java.util.Objects;
 public interface IntUnaryOperator {
 
     /**
-     * Returns the {@code int} value result of the operation upon the
-     * {@code int} operand.
+     * Applies this operator to the given operand.
      *
-     * @param operand the operand value
-     * @return the operation result value
+     * @param operand the operand
+     * @return the operator result
      */
     int applyAsInt(int operand);
 
     /**
-     * Compose a new function which applies the provided function followed by
-     * this function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed operator that first applies the {@code before}
+     * operator to its input, and then applies this operator to the result.
+     * If evaluation of either operator throws an exception, it is relayed to
+     * the caller of the composed operator.
      *
-     * @param before an additional function to be applied before this function
-     * is applied
-     * @return a function which performs the provided function followed by this
-     * function
+     * @param before the operator to apply before this operator is applied
+     * @return a composed operator that first applies the {@code before}
+     * operator and then applies this operator
      * @throws NullPointerException if before is null
+     *
+     * @see #andThen(IntUnaryOperator)
      */
     default IntUnaryOperator compose(IntUnaryOperator before) {
         Objects.requireNonNull(before);
@@ -63,15 +67,17 @@ public interface IntUnaryOperator {
     }
 
     /**
-     * Compose a new function which applies this function followed by the
-     * provided function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed operator that first applies this operator to
+     * its input, and then applies the {@code after} operator to the result.
+     * If evaluation of either operator throws an exception, it is relayed to
+     * the caller of the composed operator.
      *
-     * @param after an additional function to be applied after this function is
-     * applied
-     * @return a function which performs this function followed by the provided
-     * function followed
+     * @param after the operator to apply after this operator is applied
+     * @return a composed operator that first applies this operator and then
+     * applies the {@code after} operator
      * @throws NullPointerException if after is null
+     *
+     * @see #compose(IntUnaryOperator)
      */
     default IntUnaryOperator andThen(IntUnaryOperator after) {
         Objects.requireNonNull(after);
@@ -79,9 +85,9 @@ public interface IntUnaryOperator {
     }
 
     /**
-     * Returns a unary operator that provides its input value as the result.
+     * Returns a unary operator that always returns its input argument.
      *
-     * @return a unary operator that provides its input value as the result
+     * @return a unary operator that always returns its input argument
      */
     static IntUnaryOperator identity() {
         return t -> t;

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

@@ -25,24 +25,26 @@
 package java.util.function;
 
 /**
- * An operation on two {@code long} operands yielding a {@code long} result.
- * This is the primitive type specialization of {@link BinaryOperator} for
- * {@code long}.
+ * Represents an operation upon two {@code long}-valued operands and producing a
+ * {@code long}-valued result.   This is the primitive type specialization of
+ * {@link BinaryOperator} for {@code long}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(long, long)}.
  *
  * @see BinaryOperator
+ * @see LongUnaryOperator
  * @since 1.8
  */
 @FunctionalInterface
 public interface LongBinaryOperator {
 
     /**
-     * Returns the {@code long} result of the operation upon the {@code long}
-     * operands. The parameters are named {@code left} and {@code right} for
-     * operations where the order of parameters matters.
+     * Applies this operator to the given operands.
      *
-     * @param left the left operand value
-     * @param right  the right operand value
-     * @return the result of the operation
+     * @param left the first operand
+     * @param right the second operand
+     * @return the operator result
      */
     long applyAsLong(long left, long right);
 }

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

@@ -27,10 +27,13 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation which accepts a single long argument and returns no result.
- * This is the {@code long}-consuming primitive type specialization of
- * {@link Consumer}. Unlike most other functional interfaces, {@code LongConsumer}
- * is expected to operate via side-effects.
+ * Represents an operation that accepts a single {@code long}-valued argument and
+ * returns no result.  This is the primitive type specialization of
+ * {@link Consumer} for {@code long}.  Unlike most other functional interfaces,
+ * {@code LongConsumer} is expected to operate via side-effects.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(long)}.
  *
  * @see Consumer
  * @since 1.8
@@ -39,30 +42,26 @@ import java.util.Objects;
 public interface LongConsumer {
 
     /**
-     * Accept an input value.
+     * Performs this operation on the given argument.
      *
-     * @param value the input value
+     * @param value the input argument
      */
     void accept(long value);
 
     /**
-     * Returns a {@code LongConsumer} which performs, in sequence, the operation
-     * represented by this object followed by the operation represented by
-     * another {@code LongConsumer}.
-     *
-     * <p>Any exceptions thrown by either {@code accept} method are relayed
-     * to the caller; if performing this operation throws an exception, the
-     * other operation will not be performed.
+     * Returns a composed {@code LongConsumer} that performs, in sequence, this
+     * operation followed by the {@code after} operation. If performing either
+     * operation throws an exception, it is relayed to the caller of the
+     * composed operation.  If performing this operation throws an exception,
+     * the {@code after} operation will not be performed.
      *
-     * @param other a LongConsumer which will be chained after this
-     * LongConsumer
-     * @return a LongConsumer which performs in sequence the {@code accept} method
-     * of this LongConsumer and the {@code accept} method of the specified LongConsumer
-     * operation
-     * @throws NullPointerException if other is null
+     * @param after the operation to perform after this operation
+     * @return a composed {@code LongConsumer} that performs in sequence this
+     * operation followed by the {@code after} operation
+     * @throws NullPointerException if {@code after} is null
      */
-    default LongConsumer chain(LongConsumer other) {
-        Objects.requireNonNull(other);
-        return (long t) -> { accept(t); other.accept(t); };
+    default LongConsumer andThen(LongConsumer after) {
+        Objects.requireNonNull(after);
+        return (long t) -> { accept(t); after.accept(t); };
     }
 }

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

@@ -25,11 +25,14 @@
 package java.util.function;
 
 /**
- * Apply a function to the long-valued input argument, yielding an appropriate
- * result. This is the {@code long}-consuming primitive specialization for
+ * Represents a function that accepts a long-valued argument and produces a
+ * result.  This is the {@code long}-consuming primitive specialization for
  * {@link Function}.
  *
- * @param <R> the type of output objects from the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #apply(long)}.
+ *
+ * @param <R> the type of the result of the function
  *
  * @see Function
  * @since 1.8
@@ -38,9 +41,9 @@ package java.util.function;
 public interface LongFunction<R> {
 
     /**
-     * Compute the result of applying the function to the input argument
+     * Applies this function to the given argument.
      *
-     * @param value the input value
+     * @param value the function argument
      * @return the function result
      */
     R apply(long value);

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

@@ -27,8 +27,12 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * Determines if the {@code long} input value matches some criteria. This is the
- * {@code long}-consuming primitive type specialization of {@link Predicate}.
+ * Represents a predicate (boolean-valued function) of one {@code long}-valued
+ * argument. This is the {@code long}-consuming primitive type specialization of
+ * {@link Predicate}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #test(long)}.
  *
  * @see Predicate
  * @since 1.8
@@ -37,37 +41,40 @@ import java.util.Objects;
 public interface LongPredicate {
 
     /**
-     * Returns {@code true} if the input value matches some criteria.
+     * Evaluates this predicate on the given argument.
      *
-     * @param value the value to be tested
-     * @return {@code true} if the input value matches some criteria, otherwise
-     * {@code false}
+     * @param value the input argument
+     * @return {@code true} if the input argument matches the predicate,
+     * otherwise {@code false}
      */
     boolean test(long value);
 
     /**
-     * Returns a predicate which evaluates to {@code true} only if this
-     * predicate and the provided predicate both evaluate to {@code true}. If
-     * this predicate returns {@code false} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * AND of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code false}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ANDed with this predicate
-     * @return a new predicate which returns {@code true} only if both
-     * predicates return {@code true}
+     * @param other a predicate that will be logically-ANDed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * AND of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default LongPredicate and(LongPredicate p) {
-        Objects.requireNonNull(p);
-        return (value) -> test(value) && p.test(value);
+    default LongPredicate and(LongPredicate other) {
+        Objects.requireNonNull(other);
+        return (value) -> test(value) && other.test(value);
     }
 
     /**
-     * Returns a predicate which negates the result of this predicate.
+     * Returns a predicate that represents the logical negation of this
+     * predicate.
      *
-     * @return a new predicate who's result is always the opposite of this
+     * @return a predicate that represents the logical negation of this
      * predicate
      */
     default LongPredicate negate() {
@@ -75,22 +82,23 @@ public interface LongPredicate {
     }
 
     /**
-     * Returns a predicate which evaluates to {@code true} if either this
-     * predicate or the provided predicate evaluates to {@code true}. If this
-     * predicate returns {@code true} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * OR of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code true}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ORed with this predicate
-     * @return a new predicate which returns {@code true} if either predicate
-     * returns {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ORed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * OR of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default LongPredicate or(LongPredicate p) {
-        Objects.requireNonNull(p);
-        return (value) -> test(value) || p.test(value);
+    default LongPredicate or(LongPredicate other) {
+        Objects.requireNonNull(other);
+        return (value) -> test(value) || other.test(value);
     }
 }

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

@@ -25,8 +25,14 @@
 package java.util.function;
 
 /**
- * A supplier of {@code long} values. This is the {@code long}-providing
- * primitive specialization of {@link Supplier}.
+ * Represents a supplier of {@code long}-valued results.  This is the
+ * {@code long}-producing primitive specialization of {@link Supplier}.
+ *
+ * <p>There is no requirement that a distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #getAsLong()}.
  *
  * @see Supplier
  * @since 1.8
@@ -35,9 +41,9 @@ package java.util.function;
 public interface LongSupplier {
 
     /**
-     * Returns a {@code long} value.
+     * Gets a result.
      *
-     * @return a {@code long} value
+     * @return a result
      */
     long getAsLong();
 }

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

@@ -25,22 +25,24 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code long}-to-{@code double} specialization for {@link Function}.
+ * Represents a function that accepts a long-valued argument and produces a
+ * double-valued result.  This is the {@code long}-to-{@code double} primitive
+ * specialization for {@link Function}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(long)}.
  *
  * @see Function
- * @see DoubleToLongFunction
- * @see IntToDoubleFunction
  * @since 1.8
  */
 @FunctionalInterface
 public interface LongToDoubleFunction {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given argument.
      *
-     * @param value the input value
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
     double applyAsDouble(long value);
 }

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

@@ -25,22 +25,24 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code long}-to-{@code int} specialization for {@link Function}.
+ * Represents a function that accepts a long-valued argument and produces an
+ * int-valued result.  This is the {@code long}-to-{@code int} primitive
+ * specialization for {@link Function}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(long)}.
  *
  * @see Function
- * @see IntToLongFunction
- * @see DoubleToIntFunction
  * @since 1.8
  */
 @FunctionalInterface
 public interface LongToIntFunction {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given argument.
      *
-     * @param value the input value
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
     int applyAsInt(long value);
 }

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

@@ -27,9 +27,12 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * An operation on a single {@code long} operand yielding a {@code long} result.
- * This is the primitive type specialization of {@link UnaryOperator} for
- * {@code long}.
+ * Represents an operation on a single {@code long}-valued operand that produces
+ * a {@code long}-valued result.  This is the primitive type specialization of
+ * {@link UnaryOperator} for {@code long}.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(long)}.
  *
  * @see UnaryOperator
  * @since 1.8
@@ -38,24 +41,25 @@ import java.util.Objects;
 public interface LongUnaryOperator {
 
     /**
-     * Returns the {@code long} result of the operation upon the {@code long}
-     * operand.
+     * Applies this operator to the given operand.
      *
-     * @param operand the operand value
-     * @return the operation result value
+     * @param operand the operand
+     * @return the operator result
      */
     long applyAsLong(long operand);
 
     /**
-     * Compose a new function which applies the provided function followed by
-     * this function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed operator that first applies the {@code before}
+     * operator to its input, and then applies this operator to the result.
+     * If evaluation of either operator throws an exception, it is relayed to
+     * the caller of the composed operator.
      *
-     * @param before An additional function to be applied before this function
-     * is applied
-     * @return A function which performs the provided function followed by this
-     * function
+     * @param before the operator to apply before this operator is applied
+     * @return a composed operator that first applies the {@code before}
+     * operator and then applies this operator
      * @throws NullPointerException if before is null
+     *
+     * @see #andThen(LongUnaryOperator)
      */
     default LongUnaryOperator compose(LongUnaryOperator before) {
         Objects.requireNonNull(before);
@@ -63,15 +67,17 @@ public interface LongUnaryOperator {
     }
 
     /**
-     * Compose a new function which applies this function followed by the
-     * provided function.  If either function throws an exception, it is relayed
-     * to the caller.
+     * Returns a composed operator that first applies this operator to
+     * its input, and then applies the {@code after} operator to the result.
+     * If evaluation of either operator throws an exception, it is relayed to
+     * the caller of the composed operator.
      *
-     * @param after An additional function to be applied after this function is
-     * applied
-     * @return A function which performs this function followed by the provided
-     * function followed
+     * @param after the operator to apply after this operator is applied
+     * @return a composed operator that first applies this operator and then
+     * applies the {@code after} operator
      * @throws NullPointerException if after is null
+     *
+     * @see #compose(LongUnaryOperator)
      */
     default LongUnaryOperator andThen(LongUnaryOperator after) {
         Objects.requireNonNull(after);
@@ -79,9 +85,9 @@ public interface LongUnaryOperator {
     }
 
     /**
-     * Returns a unary operator that provides its input value as the result.
+     * Returns a unary operator that always returns its input argument.
      *
-     * @return a unary operator that provides its input value as the result
+     * @return a unary operator that always returns its input argument
      */
     static LongUnaryOperator identity() {
         return t -> t;

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

@@ -25,12 +25,16 @@
 package java.util.function;
 
 /**
- * An operation which accepts an object reference and a double, and returns no
- * result. This is the {@code (reference, double)} specialization of
- * {@link BiConsumer}. Unlike most other functional interfaces,
- * {@code ObjDoubleConsumer} is expected to operate via side-effects.
+ * Represents an operation that accepts an object-valued and a
+ * {@code double}-valued argument, and returns no result.  This is the
+ * {@code (reference, double)} specialization of {@link BiConsumer}.
+ * Unlike most other functional interfaces, {@code ObjDoubleConsumer} is
+ * expected to operate via side-effects.
  *
- * @param <T> Type of reference argument to {@code accept()}.
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, double)}.
+ *
+ * @param <T> the type of the object argument to the operation
  *
  * @see BiConsumer
  * @since 1.8
@@ -39,10 +43,10 @@ package java.util.function;
 public interface ObjDoubleConsumer<T> {
 
     /**
-     * Accept a set of input values.
+     * Performs this operation on the given arguments.
      *
-     * @param t an input object
-     * @param value an input value
+     * @param t the first input argument
+     * @param value the second input argument
      */
     void accept(T t, double value);
 }

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

@@ -25,12 +25,16 @@
 package java.util.function;
 
 /**
- * An operation which accepts an object reference and an int, and returns no
- * result. This is the {@code (reference, int)} specialization of
- * {@link BiConsumer}. Unlike most other functional interfaces,
- * {@code ObjIntConsumer} is expected to operate via side-effects.
+ * Represents an operation that accepts an object-valued and a
+ * {@code int}-valued argument, and returns no result.  This is the
+ * {@code (reference, int)} specialization of {@link BiConsumer}.
+ * Unlike most other functional interfaces, {@code ObjIntConsumer} is
+ * expected to operate via side-effects.
  *
- * @param <T> Type of reference argument to {@code accept()}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, int)}.
+ *
+ * @param <T> the type of the object argument to the operation
  *
  * @see BiConsumer
  * @since 1.8
@@ -39,10 +43,10 @@ package java.util.function;
 public interface ObjIntConsumer<T> {
 
     /**
-     * Accept a set of input values.
+     * Performs this operation on the given arguments.
      *
-     * @param t an input object
-     * @param value an input value
+     * @param t the first input argument
+     * @param value the second input argument
      */
     void accept(T t, int value);
 }

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

@@ -25,12 +25,16 @@
 package java.util.function;
 
 /**
- * An operation which accepts an object reference and a long, and returns no
- * result. This is the {@code (reference, long)} specialization of
- * {@link BiConsumer}. Unlike most other functional interfaces,
- * {@code ObjLongConsumer} is expected to operate via side-effects.
+ * Represents an operation that accepts an object-valued and a
+ * {@code long}-valued argument, and returns no result.  This is the
+ * {@code (reference, long)} specialization of {@link BiConsumer}.
+ * Unlike most other functional interfaces, {@code ObjLongConsumer} is
+ * expected to operate via side-effects.
  *
- * @param <T> Type of reference argument to {@code accept()}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #accept(Object, long)}.
+ *
+ * @param <T> the type of the object argument to the operation
  *
  * @see BiConsumer
  * @since 1.8
@@ -39,10 +43,10 @@ package java.util.function;
 public interface ObjLongConsumer<T> {
 
     /**
-     * Accept a set of input values.
+     * Performs this operation on the given arguments.
      *
-     * @param t an input object
-     * @param value an input value
+     * @param t the first input argument
+     * @param value the second input argument
      */
     void accept(T t, long value);
 }

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

@@ -27,9 +27,12 @@ package java.util.function;
 import java.util.Objects;
 
 /**
- * Determines if the input object matches some criteria.
+ * Represents a predicate (boolean-valued function) of one argument.
  *
- * @param <T> the type of argument to {@code test}
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #test(Object)}.
+ *
+ * @param <T> the type of the input to the predicate
  *
  * @since 1.8
  */
@@ -37,76 +40,80 @@ import java.util.Objects;
 public interface Predicate<T> {
 
     /**
-     * Returns {@code true} if the input object matches some criteria.
+     * Evaluates this predicate on the given argument.
      *
-     * @param t the input object
-     * @return {@code true} if the input object matches some criteria, otherwise
-     * {@code false}
+     * @param t the input argument
+     * @return {@code true} if the input argument matches the predicate,
+     * otherwise {@code false}
      */
     boolean test(T t);
 
     /**
-     * Returns a predicate which evaluates to {@code true} only if this
-     * predicate and the provided predicate both evaluate to {@code true}. If
-     * this predicate returns {@code false} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * AND of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code false}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ANDed with this predicate
-     * @return a new predicate which returns {@code true} only if both
-     * predicates return {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ANDed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * AND of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default Predicate<T> and(Predicate<? super T> p) {
-        Objects.requireNonNull(p);
-        return (t) -> test(t) && p.test(t);
+    default Predicate<T> and(Predicate<? super T> other) {
+        Objects.requireNonNull(other);
+        return (t) -> test(t) && other.test(t);
     }
 
     /**
-     * Returns a predicate which negates the result of this predicate.
-     *
-     * @return a new predicate who's result is always the opposite of this
+     * Returns a predicate that represents the logical negation of this
      * predicate.
+     *
+     * @return a predicate that represents the logical negation of this
+     * predicate
      */
     default Predicate<T> negate() {
         return (t) -> !test(t);
     }
 
     /**
-     * Returns a predicate which evaluates to {@code true} if either this
-     * predicate or the provided predicate evaluates to {@code true}. If this
-     * predicate returns {@code true} then the remaining predicate is not
-     * evaluated.
+     * Returns a composed predicate that represents a short-circuiting logical
+     * OR of this predicate and another.  When evaluating the composed
+     * predicate, if this predicate is {@code true}, then the {@code other}
+     * predicate is not evaluated.
      *
-     * <p>Any exceptions thrown by either {@code test} method are relayed
-     * to the caller; if performing first operation throws an exception, the
-     * second operation will not be performed.
+     * <p>Any exceptions thrown during evaluation of either predicate are relayed
+     * to the caller; if evaluation of this predicate throws an exception, the
+     * {@code other} predicate will not be evaluated.
      *
-     * @param p a predicate which will be logically-ORed with this predicate
-     * @return a new predicate which returns {@code true} if either predicate
-     * returns {@code true}
-     * @throws NullPointerException if p is null
+     * @param other a predicate that will be logically-ORed with this
+     *              predicate
+     * @return a composed predicate that represents the short-circuiting logical
+     * OR of this predicate and the {@code other} predicate
+     * @throws NullPointerException if other is null
      */
-    default Predicate<T> or(Predicate<? super T> p) {
-        Objects.requireNonNull(p);
-        return (t) -> test(t) || p.test(t);
+    default Predicate<T> or(Predicate<? super T> other) {
+        Objects.requireNonNull(other);
+        return (t) -> test(t) || other.test(t);
     }
 
     /**
-     * Returns a predicate who's result matches
-     * {@code Objects.equals(target, t)}.
+     * Returns a predicate that tests if two arguments are equal according
+     * to {@link Objects#equals(Object, Object)}.
      *
-     * @param <T> the type of values evaluated by the predicate
-     * @param target the target value to be compared for equality
-     * @return a predicate who's result matches
-     * {@code Objects.equals(target, t)}
+     * @param <T> the type of arguments to the predicate
+     * @param targetRef the object reference with which to compare for equality,
+     *               which may be {@code null}
+     * @return a predicate that tests if two arguments are equal according
+     * to {@link Objects#equals(Object, Object)}
      */
-    static <T> Predicate<T> isEqual(Object target) {
-        return (null == target)
+    static <T> Predicate<T> isEqual(Object targetRef) {
+        return (null == targetRef)
                 ? Objects::isNull
-                : object -> target.equals(object);
+                : object -> targetRef.equals(object);
     }
 }

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

@@ -25,10 +25,15 @@
 package java.util.function;
 
 /**
- * A supplier of objects. The result objects are either created during the
- * invocation of {@link #get} or by some prior action.
+ * Represents a supplier of results.
  *
- * @param <T> The type of objects returned by {@code get}
+ * <p>There is no requirement that a new or distinct result be returned each
+ * time the supplier is invoked.
+ *
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #get()}.
+ *
+ * @param <T> the type of results supplied by this supplier
  *
  * @since 1.8
  */
@@ -36,9 +41,9 @@ package java.util.function;
 public interface Supplier<T> {
 
     /**
-     * Returns an object.
+     * Gets a result.
      *
-     * @return an object
+     * @return a result
      */
     T get();
 }

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

@@ -25,13 +25,15 @@
 package java.util.function;
 
 /**
- * Apply a function to the input arguments, yielding an appropriate result.
- * This is the {@code double}-bearing specialization for {@link BiFunction}.
+ * Represents a function that accepts two arguments and produces a double-valued
+ * result.  This is the {@code double}-producing primitive specialization for
+ * {@link BiFunction}.
  *
- * @param <T> the type of the first argument to the {@code applyAsDouble}
- * operation.
- * @param <U> the type of the second argument to the {@code applyAsDouble}
- * operation.
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
  *
  * @see BiFunction
  * @since 1.8
@@ -40,11 +42,11 @@ package java.util.function;
 public interface ToDoubleBiFunction<T, U> {
 
     /**
-     * Compute the result of applying the function to the input arguments
+     * Applies this function to the given arguments.
      *
-     * @param t an input object
-     * @param u an input object
-     * @return the function result value
+     * @param t the first function argument
+     * @param u the second function argument
+     * @return the function result
      */
     double applyAsDouble(T t, U u);
 }

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

@@ -25,10 +25,13 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code double}-bearing specialization for {@link Function}.
+ * Represents a function that produces a double-valued result.  This is the
+ * {@code double}-producing primitive specialization for {@link Function}.
  *
- * @param <T> the type of input objects to the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsDouble(Object)}.
+ *
+ * @param <T> the type of the input to the function
  *
  * @see Function
  * @since 1.8
@@ -37,10 +40,10 @@ package java.util.function;
 public interface ToDoubleFunction<T> {
 
     /**
-     * Compute the result of applying the function to the input argument
+     * Applies this function to the given argument.
      *
-     * @param t the input object
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
-    double applyAsDouble(T t);
+    double applyAsDouble(T value);
 }

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

@@ -25,13 +25,15 @@
 package java.util.function;
 
 /**
- * Apply a function to the input arguments, yielding an appropriate result.
- * This is the {@code int}-bearing specialization for {@link BiFunction}.
+ * Represents a function that accepts two arguments and produces an int-valued
+ * result.  This is the {@code int}-producing primitive specialization for
+ * {@link BiFunction}.
  *
- * @param <T> the type of the first argument to the {@code applyAsInt}
- * operation
- * @param <U> the type of the second argument to the {@code applyAsInt}
- * operation
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
  *
  * @see BiFunction
  * @since 1.8
@@ -40,11 +42,11 @@ package java.util.function;
 public interface ToIntBiFunction<T, U> {
 
     /**
-     * Compute the result of applying the function to the input arguments
+     * Applies this function to the given arguments.
      *
-     * @param t an input object
-     * @param u an input object
-     * @return the function result value
+     * @param t the first function argument
+     * @param u the second function argument
+     * @return the function result
      */
     int applyAsInt(T t, U u);
 }

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

@@ -25,10 +25,13 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code int}-bearing specialization for {@link Function}.
+ * Represents a function that produces an int-valued result.  This is the
+ * {@code int}-producing primitive specialization for {@link Function}.
  *
- * @param <T> the type of input objects to the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsInt(Object)}.
+ *
+ * @param <T> the type of the input to the function
  *
  * @see Function
  * @since 1.8
@@ -37,10 +40,10 @@ package java.util.function;
 public interface ToIntFunction<T> {
 
     /**
-     * Compute the result of applying the function to the input arguments
+     * Applies this function to the given argument.
      *
-     * @param t the input object
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
-    int applyAsInt(T t);
+    int applyAsInt(T value);
 }

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

@@ -25,13 +25,15 @@
 package java.util.function;
 
 /**
- * Apply a function to the input arguments, yielding an appropriate result.
- * This is the {@code long}-bearing specialization for {@link BiFunction}.
+ * Represents a function that accepts two arguments and produces a long-valued
+ * result.  This is the {@code long}-producing primitive specialization for
+ * {@link BiFunction}.
  *
- * @param <T> the type of the first argument to the {@code applyAsLong}
- * operation.
- * @param <U> the type of the second argument to the {@code applyAsLong}
- * operation.
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(Object, Object)}.
+ *
+ * @param <T> the type of the first argument to the function
+ * @param <U> the type of the second argument to the function
  *
  * @see BiFunction
  * @since 1.8
@@ -40,11 +42,11 @@ package java.util.function;
 public interface ToLongBiFunction<T, U> {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given arguments.
      *
-     * @param t an input object
-     * @param u an input object
-     * @return the function result value
+     * @param t the first function argument
+     * @param u the second function argument
+     * @return the function result
      */
     long applyAsLong(T t, U u);
 }

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

@@ -25,10 +25,13 @@
 package java.util.function;
 
 /**
- * Apply a function to the input argument, yielding an appropriate result.
- * This is the {@code long}-bearing specialization for {@link Function}.
+ * Represents a function that produces a long-valued result.  This is the
+ * {@code long}-producing primitive specialization for {@link Function}.
  *
- * @param <T> the type of input objects to the function
+ * <p>This is a <a href="package-summary.html">functional interface</a>
+ * whose functional method is {@link #applyAsLong(Object)}.
+ *
+ * @param <T> the type of the input to the function
  *
  * @see Function
  * @since 1.8
@@ -37,10 +40,10 @@ package java.util.function;
 public interface ToLongFunction<T> {
 
     /**
-     * Compute the result of applying the function to the input arguments.
+     * Applies this function to the given argument.
      *
-     * @param t the input object
-     * @return the function result value
+     * @param value the function argument
+     * @return the function result
      */
-    long applyAsLong(T t);
+    long applyAsLong(T value);
 }

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

@@ -25,11 +25,14 @@
 package java.util.function;
 
 /**
- * An operation upon a single operand yielding a result. The operand and the
- * result are of the same type. This is a specialization of {@code Function} for
+ * Represents an operation on a single operand that produces a result of the
+ * same type as its operand.  This is a specialization of {@code Function} for
  * the case where the operand and result are of the same type.
  *
- * @param <T> the type of operand 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)}.
+ *
+ * @param <T> the type of the operand and result of the operator
  *
  * @see Function
  * @since 1.8
@@ -38,10 +41,10 @@ package java.util.function;
 public interface UnaryOperator<T> extends Function<T, T> {
 
     /**
-     * Returns a unary operator that provides its input value as the result.
+     * Returns a unary operator that always returns its input argument.
      *
-     * @param <T> the type of the input and output objects to the function
-     * @return a unary operator that provides its input value as the result
+     * @param <T> the type of the input and output of the operator
+     * @return a unary operator that always returns its input argument
      */
     static <T> UnaryOperator<T> identity() {
         return t -> t;

src/share/classes/java/util/function/package-info.java

 /*
- * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2012, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,56 +25,82 @@
 
 /**
  * <em>Functional interfaces</em> provide target types for lambda expressions
- * and method references.  Each functional interface has a single abstract method
+ * and method references.  Each functional interface has a single abstract
+ * method, called the <em>functional method</em> for that functional interface,
  * to which the lambda expression's parameter and return types are matched or
- * adapted.  Functional interfaces can provide a target type in multiple contexts,
- * such as assignment context, method invocation, or cast context:
+ * adapted.  Functional interfaces can provide a target type in multiple
+ * contexts, such as assignment context, method invocation, or cast context:
  *
  * <pre>{@code
+ *     // Assignment context
  *     Predicate<String> p = String::isEmpty;
  *
+ *     // Method invocation context
  *     stream.filter(e -> e.getSize() > 10)...
  *
+ *     // Cast context
  *     stream.map((ToIntFunction) e -> e.getSize())...
  * }</pre>
  *
- * <p>The interfaces in this package are functional interfaces used by the JDK,
- * and are available to be used by user code as well.  While they do not identify
- * a complete set of function shapes to which lambda expressions might be adapted,
- * they provide enough to cover common requirements.
+ * <p>The interfaces in this package are general purpose functional interfaces
+ * used by the JDK, and are available to be used by user code as well.  While
+ * they do not identify a complete set of function shapes to which lambda
+ * expressions might be adapted, they provide enough to cover common
+ * requirements. Other functional interfaces provided for specific purposes,
+ * such as {@link java.io.FileFilter}, are defined in the packages where they
+ * are used.
  *
- * <p>The interfaces in this package are annotated with @{link FunctionalInterface}.
- * This annotation is not a requirement for the compiler to recognize an interface
- * as a functional interface, but merely an aid to capture design intent and enlist the
- * help of the compiler in identifying accidental violations of design intent.
+ * <p>The interfaces in this package are annotated with
+ * {@link java.lang.FunctionalInterface}. This annotation is not a requirement
+ * for the compiler to recognize an interface as a functional interface, but
+ * merely an aid to capture design intent and enlist the help of the compiler in
+ * identifying accidental violations of design intent.
  *
- * <p>The functional interfaces in this package follow an extensible naming convention,
- * as follows:
+ * <p>Functional interfaces often represent abstract concepts like functions,
+ * actions, or predicates.  In documenting functional interfaces, or referring
+ * to variables typed as functional interfaces, it is common to refer directly
+ * to those abstract concepts, for example using "this function" instead of
+ * "the function represented by this object".
+ *
+ * <p>The functional interfaces in this package follow an extensible naming
+ * convention, as follows:
  *
  * <ul>
- *     <li>There are several basic function shapes, including {@link java.util.function.Function} ({@code T -> R}),
- *     {@link java.util.function.Consumer} ({@code T -> void}),
- *     {@link java.util.function.Predicate} ({@code T -> boolean}),
- *     and {@link java.util.function.Supplier} ({@code () -> T}).
+ *     <li>There are several basic function shapes, including
+ *     {@link java.util.function.Function} (unary function from {@code T} to {@code R}),
+ *     {@link java.util.function.Consumer} (unary function from {@code T} to {@code void}),
+ *     {@link java.util.function.Predicate} (unary function from {@code T} to {@code boolean}),
+ *     and {@link java.util.function.Supplier} (nilary function to {@code R}).
  *     </li>
- *     <li>Function shapes have a natural arity based on how they are most commonly used.
- *     The basic shapes can be modified by an arity prefix to indicate a different arity,
- *     such as {@link java.util.function.BiFunction} ({@code (T, U) -> R}).
+ *
+ *     <li>Function shapes have a natural arity based on how they are most
+ *     commonly used.  The basic shapes can be modified by an arity prefix to
+ *     indicate a different arity, such as
+ *     {@link java.util.function.BiFunction} (binary function from {@code T} and
+ *     {@code U} to {@code R}).
  *     </li>
- *     <li>There are additional derived function shapes which extend the basic function
- *     shapes, including {@link java.util.function.UnaryOperator} (extends {@code Function}) and
- *     {@link java.util.function.BinaryOperator} (extends {@code BiFunction}).
+ *
+ *     <li>There are additional derived function shapes which extend the basic
+ *     function shapes, including {@link java.util.function.UnaryOperator}
+ *     (extends {@code Function}) and {@link java.util.function.BinaryOperator}
+ *     (extends {@code BiFunction}).
  *     </li>
- *     <li>Type parameters of functional interfaces can be specialized to primitives with
- *     additional type prefixes.  To specialize the return type for a type that has both
- *     generic return type and generic arguments, we prefix {@code ToXxx}, as in
- *     {@link java.util.function.ToIntFunction}.  Otherwise, type arguments are specialized left-to-right,
- *     as in {@link java.util.function.DoubleConsumer} or {@link java.util.function.ObjIntConsumer}.
- *     (The type prefix {@code Obj} is used to indicate that we don't want to specialize this parameter,
- *     but want to move on to the next parameter.)  These schemes can be combined as in {@code IntToDoubleFunction}.
+ *
+ *     <li>Type parameters of functional interfaces can be specialized to
+ *     primitives with additional type prefixes.  To specialize the return type
+ *     for a type that has both generic return type and generic arguments, we
+ *     prefix {@code ToXxx}, as in {@link java.util.function.ToIntFunction}.
+ *     Otherwise, type arguments are specialized left-to-right, as in
+ *     {@link java.util.function.DoubleConsumer}
+ *     or {@link java.util.function.ObjIntConsumer}.
+ *     (The type prefix {@code Obj} is used to indicate that we don't want to
+ *     specialize this parameter, but want to move on to the next parameter,
+ *     as in {@link java.util.function.ObjIntConsumer}.)
+ *     These schemes can be combined, as in {@code IntToDoubleFunction}.
  *     </li>
- *     <li>If there are specialization prefixes for all arguments, the arity prefix may be left
- *     out (as in {@link java.util.function.ObjIntConsumer}).
+ *
+ *     <li>If there are specialization prefixes for all arguments, the arity
+ *     prefix may be left out (as in {@link java.util.function.ObjIntConsumer}).
  *     </li>
  * </ul>
  *