From d540452cc5b0c419d8461ddc7a3469040a018f48 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@gmail.com>
Date: Sun, 13 Oct 2024 09:26:32 -0400
Subject: [PATCH] Add details to the ArraySorter Javadoc

---
 src/changes/changes.xml                       |  1 +
 .../org/apache/commons/lang3/ArraySorter.java | 36 +++++++++----------
 2 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 02436ce2a53..a448c90fdbf 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -56,6 +56,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action                   type="fix" dev="ggregory" due-to="Gary Gregory">Remove trailing whitespace in StopWatch exception messages.</action>
     <action issue="LANG-1754" type="fix" dev="ggregory" due-to="vhbcm">Use getAllSuperclassesAndInterfaces() in getMatchingMethod() #1289.</action>
     <action                   type="fix" dev="ggregory" due-to="Gary Gregory">Add details to the ArrayFill Javadoc.</action>
+    <action                   type="fix" dev="ggregory" due-to="Gary Gregory">Add details to the ArraySorter Javadoc.</action>
     <!-- ADD -->
     <action                   type="add" dev="ggregory" due-to="Gary Gregory">Add Strings and refactor StringUtils.</action>
     <action issue="LANG-1747" type="add" dev="ggregory" due-to="Oliver B. Fischer, Gary Gregory">Add StopWatch.run([Failable]Runnable) and get([Failable]Supplier).</action>
diff --git a/src/main/java/org/apache/commons/lang3/ArraySorter.java b/src/main/java/org/apache/commons/lang3/ArraySorter.java
index 4449fed32b9..d15144988e0 100644
--- a/src/main/java/org/apache/commons/lang3/ArraySorter.java
+++ b/src/main/java/org/apache/commons/lang3/ArraySorter.java
@@ -28,9 +28,9 @@
 public class ArraySorter {
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(byte[])
      */
@@ -42,9 +42,9 @@ public static byte[] sort(final byte[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(char[])
      */
@@ -56,9 +56,9 @@ public static char[] sort(final char[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(double[])
      */
@@ -70,9 +70,9 @@ public static double[] sort(final double[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(float[])
      */
@@ -84,9 +84,9 @@ public static float[] sort(final float[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(int[])
      */
@@ -98,9 +98,9 @@ public static int[] sort(final int[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(long[])
      */
@@ -112,9 +112,9 @@ public static long[] sort(final long[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(short[])
      */
@@ -126,10 +126,10 @@ public static short[] sort(final short[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
      * @param <T> the array type.
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @return the given array.
      * @see Arrays#sort(Object[])
      */
@@ -141,10 +141,10 @@ public static <T> T[] sort(final T[] array) {
     }
 
     /**
-     * Sorts and returns the given array.
+     * Sorts the given array into ascending order and returns it.
      *
      * @param <T> the array type.
-     * @param array the array to sort.
+     * @param array the array to sort (may be null).
      * @param comparator the comparator to determine the order of the array. A {@code null} value uses the elements'
      *        {@link Comparable natural ordering}.
      * @return the given array.