Please review: 4722265 (spec str) StringBuffer.ensureCapacity() should mention that capacity is mutable

[Chris Hegarty]

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
>