A DESCRIPTION OF THE PROBLEM :
The documentation for StringBuilder / StringBuffer capacity() is currently:
> The capacity is the amount of storage available for newly inserted characters, beyond which an allocation will occur.

However, this is misleading because "newly inserted characters" sounds like the space remaining for appended chars. Something like the following would be clearer:
> The capacity is the amount of characters that can be stored (including already written characters), beyond which ...



---------- BEGIN SOURCE ----------
public class StringBuilderTest {
    public static void main(String[] args) {
        StringBuilder sb = new StringBuilder();
        
        int oldCap = sb.capacity();
        sb.append("test");
        int newCap = sb.capacity();
        
        // According to doc newCap should be oldCap - "test".length()
        System.out.println("Old cap: " + oldCap + ", new cap: " + newCap);
    }
}

---------- END SOURCE ----------