RFR: JDK-8236683 StringBuilder / StringBuffer capacity() doc is misleading (CSR)

[Jim Laskey]

Please review the following CSR intended to clarify the true meaning of StringBuilder::capacity and StringBuffer::capacity.

csr: https://bugs.openjdk.java.net/browse/JDK-8236683


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