I also think this is a non-issue - particularly from a report 10 years ago. I wouldn't waste time on it. You can't document every nuance of every method when used in conjunction with other methods. If you feel the need to complete this now then the shorter the better: "Note that subsequent operations on this StringBuffer can reduce the actual capacity below that requested here." David On 19/09/2012 6:20 AM, Chris Hegarty wrote:

Jim,

I'm not all that sure that this is really such an issue. The methods that can reduce the capacity seem to be clearly specified. But others may have a stronger opinion, for or against, than me.

Coming up with small concise wording for these type of issues is always difficult. I don't have a problem with yours, but how about..

* <p> Note that you cannot assume a successful invocation of * {@code ensureCapacity} will guarantee the capacity will always * be at least the size of {@code minimumCapacity}. The capacity * may change due to subsequent operations, for example {@linkplain * #timeToSize}

-Chris.

On 18/09/12 19:25, Jim Gish wrote:

...

Please review this minor usage note change for Bug 4722265:

diff -r 8a454e92aaf1 src/share/classes/java/lang/AbstractStringBuilder.java --- a/src/share/classes/java/lang/AbstractStringBuilder.java Mon Sep 17 12:40:33 2012 +0200 +++ b/src/share/classes/java/lang/AbstractStringBuilder.java Tue Sep 18 13:46:34 2012 -0400 @@ -96,6 +96,9 @@ * </ul> * If the {@code minimumCapacity} argument is nonpositive, this * method takes no action and simply returns. + * Note that a call to ensureCapacity does not guarantee an immutable + * setting of the minimum desired capacity. The capacity may change as + * the result of subsequent operations. * * @param minimumCapacity the minimum desired capacity. */

Thanks, Jim