From 3ce2b99a4c62cf45ca96153436e156d18ec92b8b Mon Sep 17 00:00:00 2001
From: Akshat Upadhyay <akshatupadhyayup@gmail.com>
Date: Fri, 19 Dec 2025 22:23:17 +0530
Subject: [PATCH 1/4] Clarify truncate method Javadoc

Improves the truncate method documentation to better describe substring behavior.
---
 src/main/java/org/apache/commons/lang3/StringUtils.java | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/main/java/org/apache/commons/lang3/StringUtils.java b/src/main/java/org/apache/commons/lang3/StringUtils.java
index e7fd432cdc9..e9b3179fc3a 100644
--- a/src/main/java/org/apache/commons/lang3/StringUtils.java
+++ b/src/main/java/org/apache/commons/lang3/StringUtils.java
@@ -8820,7 +8820,8 @@ public static String truncate(final String str, final int maxWidth) {
      * </p>
      * <ul>
      * <li>If {@code str} is less than {@code maxWidth} characters long, return it.</li>
-     * <li>Else truncate it to {@code substring(str, offset, maxWidth)}.</li>
+     * <li>Else truncate it to a substring starting at {@code offset} with a maximum length of {@code maxWidth}.</li>
+
      * <li>If {@code maxWidth} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
      * <li>If {@code offset} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
      * <li>In no case will it return a String of length greater than {@code maxWidth}.</li>

From 2d302994c0dad5ce3a61255f6302a9a237aadb74 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@users.noreply.github.com>
Date: Fri, 19 Dec 2025 13:47:24 -0500
Subject: [PATCH 2/4] Remove unnecessary line break in Javadoc comments

---
 src/main/java/org/apache/commons/lang3/StringUtils.java | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/main/java/org/apache/commons/lang3/StringUtils.java b/src/main/java/org/apache/commons/lang3/StringUtils.java
index e9b3179fc3a..8fedb12a11c 100644
--- a/src/main/java/org/apache/commons/lang3/StringUtils.java
+++ b/src/main/java/org/apache/commons/lang3/StringUtils.java
@@ -8821,7 +8821,6 @@ public static String truncate(final String str, final int maxWidth) {
      * <ul>
      * <li>If {@code str} is less than {@code maxWidth} characters long, return it.</li>
      * <li>Else truncate it to a substring starting at {@code offset} with a maximum length of {@code maxWidth}.</li>
-
      * <li>If {@code maxWidth} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
      * <li>If {@code offset} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
      * <li>In no case will it return a String of length greater than {@code maxWidth}.</li>

From 77b855122a11f12b79081852ba42632cec35b109 Mon Sep 17 00:00:00 2001
From: Akshat Upadhyay <akshatupadhyayup@gmail.com>
Date: Sat, 20 Dec 2025 11:19:24 +0530
Subject: [PATCH 3/4] Fix truncate Javadoc wording and formatting

Clarifies return value description and removes extra line break.
---
 src/main/java/org/apache/commons/lang3/StringUtils.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/apache/commons/lang3/StringUtils.java b/src/main/java/org/apache/commons/lang3/StringUtils.java
index 8fedb12a11c..4ec7d53175e 100644
--- a/src/main/java/org/apache/commons/lang3/StringUtils.java
+++ b/src/main/java/org/apache/commons/lang3/StringUtils.java
@@ -8819,8 +8819,8 @@ public static String truncate(final String str, final int maxWidth) {
      * Specifically:
      * </p>
      * <ul>
-     * <li>If {@code str} is less than {@code maxWidth} characters long, return it.</li>
-     * <li>Else truncate it to a substring starting at {@code offset} with a maximum length of {@code maxWidth}.</li>
+     * <li>If {@code str} is shorter than {@code maxWidth}, returns another String with the same characters.</li>
+     * <li>Else truncate it to a substring starting at {@code offset} with a maximum length of {@code maxWidth}.</li
      * <li>If {@code maxWidth} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
      * <li>If {@code offset} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
      * <li>In no case will it return a String of length greater than {@code maxWidth}.</li>

From 2c84a29dc623c6e3047079ef5fd75643df351755 Mon Sep 17 00:00:00 2001
From: Akshat Upadhyay <akshatupadhyayup@gmail.com>
Date: Sat, 20 Dec 2025 20:09:45 +0530
Subject: [PATCH 4/4] Fix inaccurate wording in truncate Javadoc

Updates the truncate Javadoc to clarify behavior when the String is shorter than maxWidth and that zero is a valid non-negative value.
---
 src/main/java/org/apache/commons/lang3/StringUtils.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/apache/commons/lang3/StringUtils.java b/src/main/java/org/apache/commons/lang3/StringUtils.java
index 4ec7d53175e..df9bcb8fb1d 100644
--- a/src/main/java/org/apache/commons/lang3/StringUtils.java
+++ b/src/main/java/org/apache/commons/lang3/StringUtils.java
@@ -8819,7 +8819,7 @@ public static String truncate(final String str, final int maxWidth) {
      * Specifically:
      * </p>
      * <ul>
-     * <li>If {@code str} is shorter than {@code maxWidth}, returns another String with the same characters.</li>
+     * <li>If {@code str} is shorter than {@code maxWidth}, returns a String containing the same characters.</li>
      * <li>Else truncate it to a substring starting at {@code offset} with a maximum length of {@code maxWidth}.</li
      * <li>If {@code maxWidth} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
      * <li>If {@code offset} is less than {@code 0}, throw an {@link IllegalArgumentException}.</li>
@@ -8861,7 +8861,7 @@ public static String truncate(final String str, final int maxWidth) {
      *
      * @param str      the String to truncate, may be null.
      * @param offset   left edge of source String.
-     * @param maxWidth maximum length of result String, must be positive.
+     * @param maxWidth maximum length of result String, must be non-negative.
      * @return truncated String, {@code null} if null String input.
      * @throws IllegalArgumentException If {@code offset} or {@code maxWidth} is less than {@code 0}.
      * @since 3.5