Summary

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,

Problem

The current description implies that capacity is space available for new or additional characters. Capacity is the space available in total.

Solution

Update the javadoc to clarify.

Specification

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
      */