OpenJDK / lambda / lambda / jdk
changeset 8899:c78083093dab
Review feedbacks on javadoc
| author | henryjen |
|---|---|
| date | Tue, 25 Jun 2013 20:53:53 -0700 |
| parents | 8975674bfabc |
| children | 85308d92a4d6 |
| files | src/share/classes/java/util/Comparator.java src/share/classes/java/util/Map.java src/share/classes/java/util/function/BinaryOperator.java |
| diffstat | 3 files changed, 78 insertions(+), 74 deletions(-) [+] |
line wrap: on
line diff
--- a/src/share/classes/java/util/Comparator.java Tue Jun 25 15:47:24 2013 -0700 +++ b/src/share/classes/java/util/Comparator.java Tue Jun 25 20:53:53 2013 -0700 @@ -177,7 +177,7 @@ * Returns a comparator that imposes the reverse ordering of this * comparator. * - * @return A comparator that imposes the reverse ordering of this + * @return a comparator that imposes the reverse ordering of this * comparator. * @since 1.8 */ @@ -186,7 +186,7 @@ } /** - * Constructs a lexicographic order comparator with another comparator. + * Returns a lexicographic-order comparator with another comparator. * If this {@code Comparator} considers two elements equal, i.e. * {@code compare(a, b) == 0}, {@code other} is used to determine the order. * @@ -194,9 +194,9 @@ * is also serializable. * * @apiNote - * To sort a collection of {@code String} based on the length and then - * case-insensitive natural ordering, the comparator can be construcred - * using following code, + * For example, to sort a collection of {@code String} based on the length + * and then case-insensitive natural ordering, the comparator can be + * composed using following code, * * <pre>{@code * Comparator<String> cmp = Comparator.comparing(String::length) @@ -205,7 +205,7 @@ * * @param other the other comparator to be used when this comparator * compares two objects that are equal. - * @return A lexicographic order comparator composed of this and then the + * @return a lexicographic-order comparator composed of this and then the * other comparator * @throws NullPointerException if the argument is null. * @since 1.8 @@ -219,17 +219,17 @@ } /** - * Constructs a lexicographic order comparator with a function that + * Returns a lexicographic-order comparator with a function that * extracts a key to be compared with the given {@code Comparator}. * - * @implSpec This default implementation calls {@code + * @implSpec This default implementation behaves as if {@code * thenComparing(comparing(keyExtractor, cmp))}. * - * @param <U> The type of the sort key + * @param <U> the type of the sort key * @param keyExtractor the function used to extract the sort key * @param keyComparator the {@code Comparator} used to compare the sort key - * @return A lexicographic order comparator composed of this and then the - * key comparator. + * @return a lexicographic-order comparator composed of this comparator + * and then comparing on the key extracted by the keyExtractor function * @throws NullPointerException if the argument is null. * @see #comparing(Function, Comparator) * @see #thenComparing(Comparator) @@ -243,16 +243,16 @@ } /** - * Constructs a lexicographic order comparator with a function that + * Returns a lexicographic-order comparator with a function that * extracts a {@code Comparable} sort key. * - * @implSpec This default implementation calls {@code + * @implSpec This default implementation behaves as if {@code * thenComparing(comparing(keyExtractor))}. * - * @param <U> The type of the {@link Comparable} sort key + * @param <U> the type of the {@link Comparable} sort key * @param keyExtractor the function used to extract the {@link * Comparable} sort key - * @return A lexicographic order comparator composed of this and then the + * @return a lexicographic-order comparator composed of this and then the * {@link Comparable} sort key. * @throws NullPointerException if the argument is null. * @see #comparing(Function) @@ -266,14 +266,14 @@ } /** - * Constructs a lexicographic order comparator with a function that + * Returns a lexicographic-order comparator with a function that * extracts a {@code int} sort key. * - * @implSpec This default implementation calls {@code + * @implSpec This default implementation behaves as if {@code * thenComparing(comparing(keyExtractor))}. * * @param keyExtractor the function used to extract the integer sort key - * @return A lexicographic order comparator composed of this and then the + * @return a lexicographic-order comparator composed of this and then the * {@code int} sort key * @throws NullPointerException if the argument is null. * @see #comparing(ToIntFunction) @@ -285,14 +285,14 @@ } /** - * Constructs a lexicographic order comparator with a function that + * Returns a lexicographic-order comparator with a function that * extracts a {@code long} sort key. * - * @implSpec This default implementation calls {@code + * @implSpec This default implementation behaves as if {@code * thenComparing(comparing(keyExtractor))}. * * @param keyExtractor the function used to extract the long sort key - * @return A lexicographic order comparator composed of this and then the + * @return a lexicographic-order comparator composed of this and then the * {@code long} sort key * @throws NullPointerException if the argument is null. * @see #comparing(ToLongFunction) @@ -304,14 +304,14 @@ } /** - * Constructs a lexicographic order comparator with a function that + * Returns a lexicographic-order comparator with a function that * extracts a {@code double} sort key. * - * @implSpec This default implementation calls {@code + * @implSpec This default implementation behaves as if {@code * thenComparing(comparing(keyExtractor))}. * * @param keyExtractor the function used to extract the double sort key - * @return A lexicographic order comparator composed of this and then the + * @return a lexicographic-order comparator composed of this and then the * {@code double} sort key * @throws NullPointerException if the argument is null. * @see #comparing(ToDoubleFunction) @@ -329,10 +329,9 @@ * <p>The returned comparator is serializable and throws {@link * NullPointerException} when comparing {@code null}. * - * @param <T> The {@link Comparable} type of element to be compared - * @return A comparator that imposes the reverse of the <i>natural - * ordering</i> on a collection of objects that implement - * the {@link Comparable} interface. + * @param <T> the {@link Comparable} type of element to be compared + * @return a comparator that imposes the reverse of the <i>natural + * ordering</i> on {@code Comparable} objects. * @see Comparable * @since 1.8 */ @@ -341,16 +340,15 @@ } /** - * Returns a comparator that compares {@link Comparable} type in natural + * Returns a comparator that compares {@link Comparable} objects in natural * order. * * <p>The returned comparator is serializable and throws {@link * NullPointerException} when comparing {@code null}. * - * @param <T> The {@link Comparable} type of element to be compared - * @return A comparator that imposes the <i>natural ordering</i> on a - * collection of objects that implement the {@link Comparable} - * interface. + * @param <T> the {@link Comparable} type of element to be compared + * @return a comparator that imposes the <i>natural ordering</i> on {@code + * Comparable} objects. * @see Comparable * @since 1.8 */ @@ -369,8 +367,10 @@ * is serializable. * * @param <T> the type of the elements to be compared - * @param comparator A {@code Comparator} for comparing non-null values - * @return A comparator that considers {@code null} to be less than non-null. + * @param comparator a {@code Comparator} for comparing non-null values + * @return a comparator that considers {@code null} to be less than + * non-null, and compares non-null objects with the supplied + * {@code Comparator}. * @since 1.8 */ public static <T> Comparator<T> nullsFirst(Comparator<? super T> comparator) { @@ -388,8 +388,10 @@ * is serializable. * * @param <T> the type of the elements to be compared - * @param comparator A {@code Comparator} for comparing non-null values - * @return A comparator that considers {@code null} to be greater than non-null. + * @param comparator a {@code Comparator} for comparing non-null values + * @return a comparator that considers {@code null} to be greater than + * non-null, and compares non-null objects with the supplied + * {@code Comparator}. * @since 1.8 */ public static <T> Comparator<T> nullsLast(Comparator<? super T> comparator) { @@ -405,22 +407,22 @@ * and comparator are both serializable. * * @apiNote - * To obtain a {@code Comparator} that compares {@code Person} objects by their last name - * ignoring case differences, + * For example, to obtain a {@code Comparator} that compares {@code + * Person} objects by their last name ignoring case differences, * * <pre>{@code - * Comparator<People> cmp = Comparator.comparing( + * Comparator<Person> cmp = Comparator.comparing( * Person::getLastName, * String.CASE_INSENSITIVE_ORDER); * }</pre> * - * @param <T> The type of element to be compared - * @param <U> The type of the sort key + * @param <T> the type of element to be compared + * @param <U> the type of the sort key * @param keyExtractor the function used to extract the sort key * @param keyComparator the {@code Comparator} used to compare the sort key - * @return A comparator that compares by an extracted key using the + * @return a comparator that compares by an extracted key using the * specified {@code Comparator} - * @throws NullPointerException if the argument is null + * @throws NullPointerException if either argument is null * @since 1.8 */ public static <T, U> Comparator<T> comparing( @@ -443,18 +445,18 @@ * is also serializable. * * @apiNote - * To obtain a {@code Comparator} that compares {@code Person} objects by their last - * name, + * For example, to obtain a {@code Comparator} that compares {@code + * Person} objects by their last name, * * <pre>{@code - * Comparator<People> byLastName = Comparator.comparing(Person::getLastName); + * Comparator<Person> byLastName = Comparator.comparing(Person::getLastName); * }</pre> * - * @param <T> The type of element to be compared - * @param <U> The type of the {@code Comparable} sort key + * @param <T> the type of element to be compared + * @param <U> the type of the {@code Comparable} sort key * @param keyExtractor the function used to extract the {@link * Comparable} sort key - * @return A comparator that compares by an extracted key + * @return a comparator that compares by an extracted key * @throws NullPointerException if the argument is null * @since 1.8 */ @@ -474,9 +476,9 @@ * <p>The returned comparator is serializable if the specified function * is also serializable. * - * @param <T> The type of element to be compared + * @param <T> the type of element to be compared * @param keyExtractor the function used to extract the integer sort key - * @return A comparator that compares by an extracted key + * @return a comparator that compares by an extracted key * @see #comparing(Function) * @throws NullPointerException if the argument is null * @since 1.8 @@ -495,9 +497,9 @@ * <p>The returned comparator is serializable if the specified function is * also serializable. * - * @param <T> The type of element to be compared + * @param <T> the type of element to be compared * @param keyExtractor the function used to extract the long sort key - * @return A comparator that compares by an extracted key + * @return a comparator that compares by an extracted key * @see #comparing(Function) * @throws NullPointerException if the argument is null * @since 1.8 @@ -516,9 +518,9 @@ * <p>The returned comparator is serializable if the specified function * is also serializable. * - * @param <T> The type of element to be compared + * @param <T> the type of element to be compared * @param keyExtractor the function used to extract the double sort key - * @return A comparator that compares by an extracted key + * @return a comparator that compares by an extracted key * @see #comparing(Function) * @throws NullPointerException if the argument is null * @since 1.8
--- a/src/share/classes/java/util/Map.java Tue Jun 25 15:47:24 2013 -0700 +++ b/src/share/classes/java/util/Map.java Tue Jun 25 20:53:53 2013 -0700 @@ -453,11 +453,11 @@ * Returns a comparator that compares {@link Map.Entry} in natural order on key. * * <p>The returned comparator is serializable and throws {@link - * NullPointerException} when comparing a map with a null key. + * NullPointerException} when comparing an entry with a null key. * - * @param <K> {@link Comparable} key type - * @param <V> value type - * @return A comparator that compares {@link Map.Entry} in natural order on key. + * @param <K> the {@link Comparable} type of then map keys + * @param <V> the type of the map values + * @return a comparator that compares {@link Map.Entry} in natural order on key. * @see Comparable */ public static <K extends Comparable<? super K>, V> Comparator<Map.Entry<K,V>> comparingByKey() { @@ -469,11 +469,11 @@ * Returns a comparator that compares {@link Map.Entry} in natural order on value. * * <p>The returned comparator is serializable and throws {@link - * NullPointerException} when comparing a map with null values. + * NullPointerException} when comparing an entry with null values. * - * @param <K> key type - * @param <V> {@link Comparable} value type - * @return A comparator that compares {@link Map.Entry} in natural order on value. + * @param <K> the type of the map keys + * @param <V> the {@link Comparable} type of the map values + * @return a comparator that compares {@link Map.Entry} in natural order on value. * @see Comparable */ public static <K, V extends Comparable<? super V>> Comparator<Map.Entry<K,V>> comparingByValue() { @@ -488,10 +488,10 @@ * <p>The returned comparator is serializable if the specified comparator * is also serializable. * - * @param <K> key type - * @param <V> value type + * @param <K> the type of the map keys + * @param <V> the type of the map values * @param cmp the key {@link Comparator} - * @return A comparator that compares {@link Map.Entry} by the key. + * @return a comparator that compares {@link Map.Entry} by the key. */ public static <K, V> Comparator<Map.Entry<K, V>> comparingByKey(Comparator<? super K> cmp) { Objects.requireNonNull(cmp); @@ -506,10 +506,10 @@ * <p>The returned comparator is serializable if the specified comparator * is also serializable. * - * @param <K> key type - * @param <V> value type + * @param <K> the type of the map keys + * @param <V> the type of the map values * @param cmp the value {@link Comparator} - * @return A comparator that compares {@link Map.Entry} by the value. + * @return a comparator that compares {@link Map.Entry} by the value. */ public static <K, V> Comparator<Map.Entry<K, V>> comparingByValue(Comparator<? super V> cmp) { Objects.requireNonNull(cmp);
--- a/src/share/classes/java/util/function/BinaryOperator.java Tue Jun 25 15:47:24 2013 -0700 +++ b/src/share/classes/java/util/function/BinaryOperator.java Tue Jun 25 20:53:53 2013 -0700 @@ -39,12 +39,13 @@ @FunctionalInterface public interface BinaryOperator<T> extends BiFunction<T,T,T> { /** - * Constructs a {@link BinaryOperator} which returns the lesser of two elements + * Returns a {@link BinaryOperator} which returns the lesser of two elements * according to the specified {@code Comparator} * - * @param comparator A {@code Comparator} for comparing the two values + * @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) { Objects.requireNonNull(comparator); @@ -52,12 +53,13 @@ } /** - * Constructs a {@link BinaryOperator} which returns the greater of two elements + * Returns a {@link BinaryOperator} which returns the greater of two elements * according to the specified {@code Comparator} * - * @param comparator A {@code Comparator} for comparing the two values + * @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) { Objects.requireNonNull(comparator);