Skip to content

JDK-8310571: Use inline @return tag on java.util.Objects #14608

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jddarcy wants to merge 5 commits into from
Closed

JDK-8310571: Use inline @return tag on java.util.Objects #14608

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
026b3ca
JDK-8310571: Use inline @return tag on java.util.Objects
jddarcy Jun 22, 2023
7d70f9a
Merge branch 'master' into JDK-8310571
jddarcy Jun 22, 2023
54f91e8
Merge branch 'master' into JDK-8310571
jddarcy Jun 23, 2023
d97eb7a
Respond to review feedback.
jddarcy Jun 23, 2023
7fae1b7
Make sure there is not an unwanted word break around "non-null".
jddarcy Jun 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 25 additions & 45 deletions src/java.base/share/classes/java/util/Objects.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
/*
* Copyright (c) 2009, 2022, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2009, 2023, 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
Expand Down Expand Up @@ -45,8 +45,8 @@ private Objects() {
}

/**
* Returns {@code true} if the arguments are equal to each other
* and {@code false} otherwise.
* {@return {@code true} if the arguments are equal to each other
* and {@code false} otherwise}
* Consequently, if both arguments are {@code null}, {@code true}
* is returned. Otherwise, if the first argument is not {@code
* null}, equality is determined by calling the {@link
Expand All @@ -56,17 +56,15 @@ private Objects() {
*
* @param a an object
* @param b an object to be compared with {@code a} for equality
* @return {@code true} if the arguments are equal to each other
* and {@code false} otherwise
* @see Object#equals(Object)
*/
public static boolean equals(Object a, Object b) {
return (a == b) || (a != null && a.equals(b));
}

/**
* Returns {@code true} if the arguments are deeply equal to each other
* and {@code false} otherwise.
* {@return {@code true} if the arguments are deeply equal to each other
* and {@code false} otherwise}
*
* Two {@code null} values are deeply equal. If both arguments are
* arrays, the algorithm in {@link Arrays#deepEquals(Object[],
Expand All @@ -76,8 +74,6 @@ public static boolean equals(Object a, Object b) {
*
* @param a an object
* @param b an object to be compared with {@code a} for deep equality
* @return {@code true} if the arguments are deeply equal to each other
* and {@code false} otherwise
* @see Arrays#deepEquals(Object[], Object[])
* @see Objects#equals(Object, Object)
*/
Expand All @@ -91,20 +87,18 @@ else if (a == null || b == null)
}

/**
* Returns the hash code of a non-{@code null} argument and 0 for
* a {@code null} argument.
* {@return the hash code of a non-{@code null} argument and 0 for
* a {@code null} argument}
*
* @param o an object
* @return the hash code of a non-{@code null} argument and 0 for
* a {@code null} argument
* @see Object#hashCode
*/
public static int hashCode(Object o) {
return o != null ? o.hashCode() : 0;
}

/**
* Generates a hash code for a sequence of input values. The hash
* {@return a hash code for a sequence of input values} The hash
* code is generated as if all the input values were placed into an
* array, and that array were hashed by calling {@link
* Arrays#hashCode(Object[])}.
Expand All @@ -125,7 +119,6 @@ public static int hashCode(Object o) {
* value can be computed by calling {@link #hashCode(Object)}.
*
* @param values the values to be hashed
* @return a hash value of the sequence of input values
* @see Arrays#hashCode(Object[])
* @see List#hashCode
*/
Expand All @@ -134,12 +127,11 @@ public static int hash(Object... values) {
}

/**
* Returns the result of calling {@code toString} for a non-{@code
* null} argument and {@code "null"} for a {@code null} argument.
* {@return the result of calling {@code toString} for a
* non-{@code null} argument and {@code "null"} for a
* {@code null} argument}
*
* @param o an object
* @return the result of calling {@code toString} for a non-{@code
* null} argument and {@code "null"} for a {@code null} argument
* @see Object#toString
* @see String#valueOf(Object)
*/
Expand All @@ -148,16 +140,13 @@ public static String toString(Object o) {
}

/**
* Returns the result of calling {@code toString} on the first
* argument if the first argument is not {@code null} and returns
* the second argument otherwise.
* {@return the result of calling {@code toString} on the first
* argument if the first argument is not {@code null} and the
* second argument otherwise}
*
* @param o an object
* @param nullDefault string to return if the first argument is
* {@code null}
* @return the result of calling {@code toString} on the first
* argument if it is not {@code null} and the second argument
* otherwise.
* @see Objects#toString(Object)
*/
public static String toString(Object o, String nullDefault) {
Expand Down Expand Up @@ -189,8 +178,8 @@ public static String toIdentityString(Object o) {
}

/**
* Returns 0 if the arguments are identical and {@code
* c.compare(a, b)} otherwise.
* {@return 0 if the arguments are identical and {@code
* c.compare(a, b)} otherwise}
* Consequently, if both arguments are {@code null} 0
* is returned.
*
Expand All @@ -203,8 +192,6 @@ public static String toIdentityString(Object o) {
* @param a an object
* @param b an object to be compared with {@code a}
* @param c the {@code Comparator} to compare the first two arguments
* @return 0 if the arguments are identical and {@code
* c.compare(a, b)} otherwise.
* @see Comparable
* @see Comparator
*/
Expand Down Expand Up @@ -261,15 +248,13 @@ public static <T> T requireNonNull(T obj, String message) {
}

/**
* Returns {@code true} if the provided reference is {@code null} otherwise
* returns {@code false}.
* {@return {@code true} if the provided reference is {@code
Copy link
Member

@pavelrappo pavelrappo Jun 22, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See my previous comment on the "returns" verb in the doc comment for toString(Object, String). Here (IMO), you picked the better of the two options.

* null}; {@code false} otherwise}
*
* @apiNote This method exists to be used as a
* {@link java.util.function.Predicate}, {@code filter(Objects::isNull)}
*
* @param obj a reference to be checked against {@code null}
* @return {@code true} if the provided reference is {@code null} otherwise
* {@code false}
*
* @see java.util.function.Predicate
* @since 1.8
Expand All @@ -279,15 +264,13 @@ public static boolean isNull(Object obj) {
}

/**
* Returns {@code true} if the provided reference is non-{@code null}
* otherwise returns {@code false}.
* {@return {@code true} if the provided reference is non-{@code null};
* {@code false} otherwise}
*
* @apiNote This method exists to be used as a
* {@link java.util.function.Predicate}, {@code filter(Objects::nonNull)}
*
* @param obj a reference to be checked against {@code null}
* @return {@code true} if the provided reference is non-{@code null}
* otherwise {@code false}
*
* @see java.util.function.Predicate
* @since 1.8
Expand All @@ -297,15 +280,13 @@ public static boolean nonNull(Object obj) {
}

/**
* Returns the first argument if it is non-{@code null} and
* otherwise returns the non-{@code null} second argument.
* {@return the first argument if it is non-{@code null} and
* otherwise the second argument if it is non-{@code null}}
*
* @param obj an object
* @param defaultObj a non-{@code null} object to return if the first argument
* is {@code null}
* @param <T> the type of the reference
* @return the first argument if it is non-{@code null} and
* otherwise the second argument if it is non-{@code null}
* @throws NullPointerException if both {@code obj} is null and
* {@code defaultObj} is {@code null}
* @since 9
Expand All @@ -315,15 +296,14 @@ public static <T> T requireNonNullElse(T obj, T defaultObj) {
}

/**
* Returns the first argument if it is non-{@code null} and otherwise
* returns the non-{@code null} value of {@code supplier.get()}.
* {@return the first argument if it is non-{@code null} and
* otherwise the value from {@code supplier.get()} if it is
* non-{@code null}}
*
* @param obj an object
* @param supplier of a non-{@code null} object to return if the first argument
* is {@code null}
* @param <T> the type of the first argument and return type
* @return the first argument if it is non-{@code null} and otherwise
* the value from {@code supplier.get()} if it is non-{@code null}
* @throws NullPointerException if both {@code obj} is null and
* either the {@code supplier} is {@code null} or
* the {@code supplier.get()} value is {@code null}
Expand Down