The proposed change clarifies that the result from StringBuilder::capacity and StringBuffer::capacity to mean total available space and not just the space available for new characters,
The current description implies that capacity is space available for new or additional characters. Capacity is the space available in total.
Update the javadoc to clarify.
diff --git a/src/java.base/share/classes/java/lang/AbstractStringBuilder.java b/src/java.base/share/classes/java/lang/AbstractStringBuilder.java --- a/src/java.base/share/classes/java/lang/AbstractStringBuilder.java +++ b/src/java.base/share/classes/java/lang/AbstractStringBuilder.java @@ -181,9 +181,9 @@ } /** - * Returns the current capacity. The capacity is the amount of storage - * available for newly inserted characters, beyond which an allocation - * will occur. + * Returns the current capacity. The capacity is the number of characters + * that can be stored (including already written characters), beyond which + * an allocation will occur. * * @return the current capacity */