This is an automated email from the ASF dual-hosted git repository. garydgregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-lang.git
commit f3320ba6e34081bca2c7698913ac9bbb36ed2320 Author: Gary Gregory <[email protected]> AuthorDate: Sat Jul 25 08:25:26 2026 -0400 Javadoc --- .../commons/lang3/builder/CompareToBuilder.java | 544 +++++++++------------ 1 file changed, 235 insertions(+), 309 deletions(-) diff --git a/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java b/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java index e1b05f9e9..30ff79bdc 100644 --- a/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java +++ b/src/main/java/org/apache/commons/lang3/builder/CompareToBuilder.java @@ -139,7 +139,7 @@ public static Builder builder() { * Gets the registry of object pairs being traversed by the reflection * methods in the current thread. * - * @return Set the registry of objects being traversed + * @return Set the registry of objects being traversed. */ static Set<Pair<IDKey, IDKey>> getRegistry() { return REGISTRY.get(); @@ -153,8 +153,8 @@ static Set<Pair<IDKey, IDKey>> getRegistry() { * is registered in the given or swapped order. * </p> * - * @param lhs {@code this} object to lookup in registry - * @param rhs The other object to lookup on registry + * @param lhs {@code this} object to lookup in registry. + * @param rhs The other object to lookup on registry. * @return boolean {@code true} if the registry contains the given object. */ static boolean isRegistered(final Object lhs, final Object rhs) { @@ -165,13 +165,13 @@ static boolean isRegistered(final Object lhs, final Object rhs) { * Appends to {@code builder} the comparison of {@code lhs} * to {@code rhs} using the fields defined in {@code clazz}. * - * @param lhs left-hand side object - * @param rhs right-hand side object - * @param clazz {@link Class} that defines fields to be compared - * @param builder {@link CompareToBuilder} to append to - * @param useTransients whether to compare transient fields - * @param excludeFields fields to exclude - * @param forceAccessible Whether to set fields' accessible flags + * @param lhs left-hand side object. + * @param rhs right-hand side object. + * @param clazz {@link Class} that defines fields to be compared. + * @param builder {@link CompareToBuilder} to append to. + * @param useTransients whether to compare transient fields. + * @param excludeFields fields to exclude. + * @param forceAccessible Whether to set fields' accessible flags. */ private static void reflectionAppend( final Object lhs, @@ -201,29 +201,24 @@ private static void reflectionAppend( /** * Compares two {@link Object}s via reflection. - * - * <p>Fields can be private, thus {@code AccessibleObject.setAccessible} - * is used to bypass normal access control checks. This will fail under a - * security manager unless the appropriate permissions are set.</p> - * + * <p> + * Fields can be private, thus {@code AccessibleObject.setAccessible} is used to bypass normal access control checks. This will fail under a security + * manager unless the appropriate permissions are set. + * </p> * <ul> * <li>Static fields will not be compared</li> - * <li>Transient members will be not be compared, as they are likely derived - * fields</li> + * <li>Transient members will be not be compared, as they are likely derived fields</li> * <li>Superclass fields will be compared</li> * </ul> + * <p> + * If both {@code lhs} and {@code rhs} are {@code null}, they are considered equal. + * </p> * - * <p>If both {@code lhs} and {@code rhs} are {@code null}, - * they are considered equal.</p> - * - * @param lhs left-hand side object - * @param rhs right-hand side object - * @return A negative integer, zero, or a positive integer as {@code lhs} - * is less than, equal to, or greater than {@code rhs} - * @throws NullPointerException if either (but not both) parameters are - * {@code null} - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @param lhs left-hand side object. + * @param rhs right-hand side object. + * @return A negative integer, zero, or a positive integer as {@code lhs} is less than, equal to, or greater than {@code rhs}. + * @throws NullPointerException if either (but not both) parameters are {@code null}. + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. */ public static int reflectionCompare(final Object lhs, final Object rhs) { return reflectionCompare(lhs, rhs, false, null); @@ -231,31 +226,25 @@ public static int reflectionCompare(final Object lhs, final Object rhs) { /** * Compares two {@link Object}s via reflection. - * - * <p>Fields can be private, thus {@code AccessibleObject.setAccessible} - * is used to bypass normal access control checks. This will fail under a - * security manager unless the appropriate permissions are set.</p> - * + * <p> + * Fields can be private, thus {@code AccessibleObject.setAccessible} is used to bypass normal access control checks. This will fail under a security + * manager unless the appropriate permissions are set. + * </p> * <ul> * <li>Static fields will not be compared</li> - * <li>If {@code compareTransients} is {@code true}, - * compares transient members. Otherwise ignores them, as they - * are likely derived fields.</li> + * <li>If {@code compareTransients} is {@code true}, compares transient members. Otherwise ignores them, as they are likely derived fields.</li> * <li>Superclass fields will be compared</li> * </ul> + * <p> + * If both {@code lhs} and {@code rhs} are {@code null}, they are considered equal. + * </p> * - * <p>If both {@code lhs} and {@code rhs} are {@code null}, - * they are considered equal.</p> - * - * @param lhs left-hand side object - * @param rhs right-hand side object - * @param compareTransients whether to compare transient fields - * @return A negative integer, zero, or a positive integer as {@code lhs} - * is less than, equal to, or greater than {@code rhs} - * @throws NullPointerException if either {@code lhs} or {@code rhs} - * (but not both) is {@code null} - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @param lhs left-hand side object. + * @param rhs right-hand side object. + * @param compareTransients whether to compare transient fields. + * @return A negative integer, zero, or a positive integer as {@code lhs} is less than, equal to, or greater than {@code rhs}. + * @throws NullPointerException if either {@code lhs} or {@code rhs} (but not both) is {@code null}. + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. */ public static int reflectionCompare(final Object lhs, final Object rhs, final boolean compareTransients) { return reflectionCompare(lhs, rhs, compareTransients, null); @@ -263,35 +252,29 @@ public static int reflectionCompare(final Object lhs, final Object rhs, final bo /** * Compares two {@link Object}s via reflection. - * - * <p>Fields can be private, thus {@code AccessibleObject.setAccessible} - * is used to bypass normal access control checks. This will fail under a - * security manager unless the appropriate permissions are set.</p> - * + * <p> + * Fields can be private, thus {@code AccessibleObject.setAccessible} is used to bypass normal access control checks. This will fail under a security + * manager unless the appropriate permissions are set. + * </p> * <ul> * <li>Static fields will not be compared</li> - * <li>If the {@code compareTransients} is {@code true}, - * compares transient members. Otherwise ignores them, as they - * are likely derived fields.</li> - * <li>Compares superclass fields up to and including {@code reflectUpToClass}. - * If {@code reflectUpToClass} is {@code null}, compares all superclass fields.</li> + * <li>If the {@code compareTransients} is {@code true}, compares transient members. Otherwise ignores them, as they are likely derived fields.</li> + * <li>Compares superclass fields up to and including {@code reflectUpToClass}. If {@code reflectUpToClass} is {@code null}, compares all superclass + * fields.</li> * </ul> + * <p> + * If both {@code lhs} and {@code rhs} are {@code null}, they are considered equal. + * </p> * - * <p>If both {@code lhs} and {@code rhs} are {@code null}, - * they are considered equal.</p> - * - * @param lhs left-hand side object - * @param rhs right-hand side object - * @param compareTransients whether to compare transient fields - * @param reflectUpToClass last superclass for which fields are compared - * @param excludeFields fields to exclude - * @return A negative integer, zero, or a positive integer as {@code lhs} - * is less than, equal to, or greater than {@code rhs} - * @throws NullPointerException if either {@code lhs} or {@code rhs} - * (but not both) is {@code null} - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} - * @since 2.2 (2.0 as {@code reflectionCompare(Object, Object, boolean, Class)}) + * @param lhs left-hand side object. + * @param rhs right-hand side object. + * @param compareTransients whether to compare transient fields. + * @param reflectUpToClass last superclass for which fields are compared. + * @param excludeFields fields to exclude. + * @return A negative integer, zero, or a positive integer as {@code lhs} is less than, equal to, or greater than {@code rhs}. + * @throws NullPointerException if either {@code lhs} or {@code rhs} (but not both) is {@code null}. + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. + * @since 2.2 (2.0 as {@code reflectionCompare(Object, Object, boolean, Class)}). */ public static int reflectionCompare( final Object lhs, @@ -319,31 +302,25 @@ public static int reflectionCompare( /** * Compares two {@link Object}s via reflection. - * - * <p>Fields can be private, thus {@code AccessibleObject.setAccessible} - * is used to bypass normal access control checks. This will fail under a - * security manager unless the appropriate permissions are set.</p> - * + * <p> + * Fields can be private, thus {@code AccessibleObject.setAccessible} is used to bypass normal access control checks. This will fail under a security + * manager unless the appropriate permissions are set. + * </p> * <ul> * <li>Static fields will not be compared</li> - * <li>If {@code compareTransients} is {@code true}, - * compares transient members. Otherwise ignores them, as they - * are likely derived fields.</li> + * <li>If {@code compareTransients} is {@code true}, compares transient members. Otherwise ignores them, as they are likely derived fields.</li> * <li>Superclass fields will be compared</li> * </ul> + * <p> + * If both {@code lhs} and {@code rhs} are {@code null}, they are considered equal. + * </p> * - * <p>If both {@code lhs} and {@code rhs} are {@code null}, - * they are considered equal.</p> - * - * @param lhs left-hand side object - * @param rhs right-hand side object - * @param excludeFields Collection of String fields to exclude - * @return A negative integer, zero, or a positive integer as {@code lhs} - * is less than, equal to, or greater than {@code rhs} - * @throws NullPointerException if either {@code lhs} or {@code rhs} - * (but not both) is {@code null} - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @param lhs left-hand side object. + * @param rhs right-hand side object. + * @param excludeFields Collection of String fields to exclude. + * @return A negative integer, zero, or a positive integer as {@code lhs} is less than, equal to, or greater than {@code rhs}. + * @throws NullPointerException if either {@code lhs} or {@code rhs} (but not both) is {@code null}. + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. * @since 2.2 */ public static int reflectionCompare(final Object lhs, final Object rhs, final Collection<String> excludeFields) { @@ -352,31 +329,25 @@ public static int reflectionCompare(final Object lhs, final Object rhs, final Co /** * Compares two {@link Object}s via reflection. - * - * <p>Fields can be private, thus {@code AccessibleObject.setAccessible} - * is used to bypass normal access control checks. This will fail under a - * security manager unless the appropriate permissions are set.</p> - * + * <p> + * Fields can be private, thus {@code AccessibleObject.setAccessible} is used to bypass normal access control checks. This will fail under a security + * manager unless the appropriate permissions are set. + * </p> * <ul> * <li>Static fields will not be compared</li> - * <li>If {@code compareTransients} is {@code true}, - * compares transient members. Otherwise ignores them, as they - * are likely derived fields.</li> + * <li>If {@code compareTransients} is {@code true}, compares transient members. Otherwise ignores them, as they are likely derived fields.</li> * <li>Superclass fields will be compared</li> * </ul> + * <p> + * If both {@code lhs} and {@code rhs} are {@code null}, they are considered equal. + * </p> * - * <p>If both {@code lhs} and {@code rhs} are {@code null}, - * they are considered equal.</p> - * - * @param lhs left-hand side object - * @param rhs right-hand side object - * @param excludeFields array of fields to exclude - * @return A negative integer, zero, or a positive integer as {@code lhs} - * is less than, equal to, or greater than {@code rhs} - * @throws NullPointerException if either {@code lhs} or {@code rhs} - * (but not both) is {@code null} - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @param lhs left-hand side object. + * @param rhs right-hand side object. + * @param excludeFields array of fields to exclude. + * @return A negative integer, zero, or a positive integer as {@code lhs} is less than, equal to, or greater than {@code rhs}. + * @throws NullPointerException if either {@code lhs} or {@code rhs} (but not both) is {@code null}. + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. * @since 2.2 */ public static int reflectionCompare(final Object lhs, final Object rhs, final String... excludeFields) { @@ -384,11 +355,10 @@ public static int reflectionCompare(final Object lhs, final Object rhs, final St } /** - * Registers the given object pair. - * Used by the reflection methods to avoid infinite loops. + * Registers the given object pair. Used by the reflection methods to avoid infinite loops. * - * @param lhs {@code this} object to register - * @param rhs The other object to register + * @param lhs {@code this} object to register. + * @param rhs The other object to register. */ private static void register(final Object lhs, final Object rhs) { register(lhs, rhs, getRegistry()); @@ -396,13 +366,12 @@ private static void register(final Object lhs, final Object rhs) { /** * Unregisters the given object pair. - * * <p> * Used by the reflection methods to avoid infinite loops. * </p> * - * @param lhs {@code this} object to unregister - * @param rhs The other object to unregister + * @param lhs {@code this} object to unregister. + * @param rhs The other object to unregister. */ private static void unregister(final Object lhs, final Object rhs) { unregister(lhs, rhs, getRegistry(), REGISTRY); @@ -415,10 +384,10 @@ private static void unregister(final Object lhs, final Object rhs) { /** * Constructor for CompareToBuilder. - * - * <p>Starts off assuming that the objects are equal. Multiple calls are - * then made to the various append methods, followed by a call to - * {@link #toComparison} to get the result.</p> + * <p> + * Starts off assuming that the objects are equal. Multiple calls are then made to the various append methods, followed by a call to {@link #toComparison} + * to get the result. + * </p> */ public CompareToBuilder() { super(builder()); @@ -430,13 +399,12 @@ private CompareToBuilder(final Builder builder) { } /** - * Appends to the {@code builder} the comparison of - * two {@code booleans}s. + * Appends to the {@code builder} the comparison of two {@code booleans}s. * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. - */ + */ public CompareToBuilder append(final boolean lhs, final boolean rhs) { if (comparison != 0 || lhs == rhs) { return this; @@ -446,18 +414,16 @@ public CompareToBuilder append(final boolean lhs, final boolean rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code boolean} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code boolean} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(boolean, boolean)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(boolean, boolean)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final boolean[] lhs, final boolean[] rhs) { @@ -483,11 +449,10 @@ public CompareToBuilder append(final boolean[] lhs, final boolean[] rhs) { } /** - * Appends to the {@code builder} the comparison of - * two {@code byte}s. + * Appends to the {@code builder} the comparison of two {@code byte}s. * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. */ public CompareToBuilder append(final byte lhs, final byte rhs) { @@ -499,18 +464,16 @@ public CompareToBuilder append(final byte lhs, final byte rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code byte} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code byte} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(byte, byte)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(byte, byte)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final byte[] lhs, final byte[] rhs) { @@ -536,11 +499,10 @@ public CompareToBuilder append(final byte[] lhs, final byte[] rhs) { } /** - * Appends to the {@code builder} the comparison of - * two {@code char}s. + * Appends to the {@code builder} the comparison of two {@code char}s. * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. */ public CompareToBuilder append(final char lhs, final char rhs) { @@ -552,18 +514,16 @@ public CompareToBuilder append(final char lhs, final char rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code char} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code char} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(char, char)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(char, char)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final char[] lhs, final char[] rhs) { @@ -589,16 +549,16 @@ public CompareToBuilder append(final char[] lhs, final char[] rhs) { } /** - * Appends to the {@code builder} the comparison of - * two {@code double}s. - * - * <p>This handles NaNs, Infinities, and {@code -0.0}.</p> - * - * <p>It is compatible with the hash code generated by - * {@link HashCodeBuilder}.</p> + * Appends to the {@code builder} the comparison of two {@code double}s. + * <p> + * This handles NaNs, Infinities, and {@code -0.0}. + * </p> + * <p> + * It is compatible with the hash code generated by {@link HashCodeBuilder}. + * </p> * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. */ public CompareToBuilder append(final double lhs, final double rhs) { @@ -610,18 +570,16 @@ public CompareToBuilder append(final double lhs, final double rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code double} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code double} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(double, double)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(double, double)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final double[] lhs, final double[] rhs) { @@ -647,16 +605,16 @@ public CompareToBuilder append(final double[] lhs, final double[] rhs) { } /** - * Appends to the {@code builder} the comparison of - * two {@code float}s. - * - * <p>This handles NaNs, Infinities, and {@code -0.0}.</p> - * - * <p>It is compatible with the hash code generated by - * {@link HashCodeBuilder}.</p> + * Appends to the {@code builder} the comparison of two {@code float}s. + * <p> + * This handles NaNs, Infinities, and {@code -0.0}. + * </p> + * <p> + * It is compatible with the hash code generated by {@link HashCodeBuilder}. + * </p> * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. */ public CompareToBuilder append(final float lhs, final float rhs) { @@ -668,18 +626,16 @@ public CompareToBuilder append(final float lhs, final float rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code float} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code float} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(float, float)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(float, float)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final float[] lhs, final float[] rhs) { @@ -705,11 +661,10 @@ public CompareToBuilder append(final float[] lhs, final float[] rhs) { } /** - * Appends to the {@code builder} the comparison of - * two {@code int}s. + * Appends to the {@code builder} the comparison of two {@code int}s. * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. */ public CompareToBuilder append(final int lhs, final int rhs) { @@ -721,18 +676,16 @@ public CompareToBuilder append(final int lhs, final int rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code int} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code int} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(int, int)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(int, int)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final int[] lhs, final int[] rhs) { @@ -758,11 +711,10 @@ public CompareToBuilder append(final int[] lhs, final int[] rhs) { } /** - * Appends to the {@code builder} the comparison of - * two {@code long}s. + * Appends to the {@code builder} the comparison of two {@code long}s. * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. */ public CompareToBuilder append(final long lhs, final long rhs) { @@ -774,18 +726,16 @@ public CompareToBuilder append(final long lhs, final long rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code long} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code long} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(long, long)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(long, long)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final long[] lhs, final long[] rhs) { @@ -811,51 +761,42 @@ public CompareToBuilder append(final long[] lhs, final long[] rhs) { } /** - * Appends to the {@code builder} the comparison of - * two {@link Object}s. - * + * Appends to the {@code builder} the comparison of two {@link Object}s. * <ol> * <li>Check if {@code lhs == rhs}</li> - * <li>Check if either {@code lhs} or {@code rhs} is {@code null}, - * a {@code null} object is less than a non-{@code null} object</li> + * <li>Check if either {@code lhs} or {@code rhs} is {@code null}, a {@code null} object is less than a non-{@code null} object</li> * <li>Check the object contents</li> * </ol> + * <p> + * {@code lhs} must either be an array or implement {@link Comparable}. + * </p> * - * <p>{@code lhs} must either be an array or implement {@link Comparable}.</p> - * - * @param lhs left-hand side object - * @param rhs right-hand side object + * @param lhs left-hand side object. + * @param rhs right-hand side object. * @return {@code this} instance. - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. */ public CompareToBuilder append(final Object lhs, final Object rhs) { return append(lhs, rhs, null); } /** - * Appends to the {@code builder} the comparison of - * two {@link Object}s. - * + * Appends to the {@code builder} the comparison of two {@link Object}s. * <ol> * <li>Check if {@code lhs == rhs}</li> - * <li>Check if either {@code lhs} or {@code rhs} is {@code null}, - * a {@code null} object is less than a non-{@code null} object</li> + * <li>Check if either {@code lhs} or {@code rhs} is {@code null}, a {@code null} object is less than a non-{@code null} object</li> * <li>Check the object contents</li> * </ol> + * <p> + * If {@code lhs} is an array, array comparison methods will be used. Otherwise {@code comparator} will be used to compare the objects. If + * {@code comparator} is {@code null}, {@code lhs} must implement {@link Comparable} instead. + * </p> * - * <p>If {@code lhs} is an array, array comparison methods will be used. - * Otherwise {@code comparator} will be used to compare the objects. - * If {@code comparator} is {@code null}, {@code lhs} must - * implement {@link Comparable} instead.</p> - * - * @param lhs left-hand side object - * @param rhs right-hand side object - * @param comparator {@link Comparator} used to compare the objects, - * {@code null} means treat lhs as {@link Comparable} + * @param lhs left-hand side object. + * @param rhs right-hand side object. + * @param comparator {@link Comparator} used to compare the objects, {@code null} means treat lhs as {@link Comparable} * @return {@code this} instance. - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. * @since 2.0 */ public CompareToBuilder append(final Object lhs, final Object rhs, final Comparator<?> comparator) { @@ -895,50 +836,43 @@ public CompareToBuilder append(final Object lhs, final Object rhs, final Compara } /** - * Appends to the {@code builder} the deep comparison of - * two {@link Object} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@link Object} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a short length array is less than a long length array</li> - * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a short length array is less than a long length array</li> + * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li> * </ol> + * <p> + * This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays. + * </p> * - * <p>This method will also will be called for the top level of multi-dimensional, - * ragged, and multi-typed arrays.</p> - * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. */ public CompareToBuilder append(final Object[] lhs, final Object[] rhs) { return append(lhs, rhs, null); } /** - * Appends to the {@code builder} the deep comparison of - * two {@link Object} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@link Object} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a short length array is less than a long length array</li> - * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a short length array is less than a long length array</li> + * <li>Check array contents element by element using {@link #append(Object, Object, Comparator)}</li> * </ol> + * <p> + * This method will also will be called for the top level of multi-dimensional, ragged, and multi-typed arrays. + * </p> * - * <p>This method will also will be called for the top level of multi-dimensional, - * ragged, and multi-typed arrays.</p> - * - * @param lhs left-hand side array - * @param rhs right-hand side array - * @param comparator {@link Comparator} to use to compare the array elements, - * {@code null} means to treat {@code lhs} elements as {@link Comparable}. + * @param lhs left-hand side array. + * @param rhs right-hand side array. + * @param comparator {@link Comparator} to use to compare the array elements, {@code null} means to treat {@code lhs} elements as {@link Comparable}. * @return {@code this} instance. - * @throws ClassCastException if {@code rhs} is not assignment-compatible - * with {@code lhs} + * @throws ClassCastException if {@code rhs} is not assignment-compatible with {@code lhs}. * @since 2.0 */ public CompareToBuilder append(final Object[] lhs, final Object[] rhs, final Comparator<?> comparator) { @@ -964,11 +898,10 @@ public CompareToBuilder append(final Object[] lhs, final Object[] rhs, final Com } /** - * Appends to the {@code builder} the comparison of - * two {@code short}s. + * Appends to the {@code builder} the comparison of two {@code short}s. * - * @param lhs left-hand side value - * @param rhs right-hand side value + * @param lhs left-hand side value. + * @param rhs right-hand side value. * @return {@code this} instance. */ public CompareToBuilder append(final short lhs, final short rhs) { @@ -980,18 +913,16 @@ public CompareToBuilder append(final short lhs, final short rhs) { } /** - * Appends to the {@code builder} the deep comparison of - * two {@code short} arrays. - * + * Appends to the {@code builder} the deep comparison of two {@code short} arrays. * <ol> - * <li>Check if arrays are the same using {@code ==}</li> - * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> - * <li>Check array length, a shorter length array is less than a longer length array</li> - * <li>Check array contents element by element using {@link #append(short, short)}</li> + * <li>Check if arrays are the same using {@code ==}</li> + * <li>Check if for {@code null}, {@code null} is less than non-{@code null}</li> + * <li>Check array length, a shorter length array is less than a longer length array</li> + * <li>Check array contents element by element using {@link #append(short, short)}</li> * </ol> * - * @param lhs left-hand side array - * @param rhs right-hand side array + * @param lhs left-hand side array. + * @param rhs right-hand side array. * @return {@code this} instance. */ public CompareToBuilder append(final short[] lhs, final short[] rhs) { @@ -1044,10 +975,9 @@ private void appendArray(final Object lhs, final Object rhs, final Comparator<?> } /** - * Appends to the {@code builder} the {@code compareTo(Object)} - * result of the superclass. + * Appends to the {@code builder} the {@code compareTo(Object)} result of the superclass. * - * @param superCompareTo result of calling {@code super.compareTo(Object)} + * @param superCompareTo result of calling {@code super.compareTo(Object)}. * @return {@code this} instance. * @since 2.0 */ @@ -1060,12 +990,10 @@ public CompareToBuilder appendSuper(final int superCompareTo) { } /** - * Returns a negative Integer, a positive Integer, or zero as - * the {@code builder} has judged the "left-hand" side - * as less than, greater than, or equal to the "right-hand" - * side. + * Returns a negative Integer, a positive Integer, or zero as the {@code builder} has judged the "left-hand" side as less than, greater than, or equal to + * the "right-hand" side. * - * @return final comparison result as an Integer + * @return final comparison result as an Integer. * @see #toComparison() * @since 3.0 */ @@ -1075,12 +1003,10 @@ public Integer build() { } /** - * Returns a negative integer, a positive integer, or zero as - * the {@code builder} has judged the "left-hand" side - * as less than, greater than, or equal to the "right-hand" - * side. + * Returns a negative integer, a positive integer, or zero as the {@code builder} has judged the "left-hand" side as less than, greater than, or equal to + * the "right-hand" side. * - * @return final comparison result + * @return final comparison result. * @see #build() */ public int toComparison() {
