GH-141: Correct capacity behavior in BufferAllocator.buffer docstrings (#1010)

## What's Changed

Update the `BufferAllocator.buffer(long)` and
`BufferAllocator.buffer(long, BufferManager)` docstrings so they match
the actual behavior: the returned buffer’s capacity is the allocated
(possibly rounded) size, not the requested size. The previous text said
the capacity would be set to the configured size, which was incorrect.
The new text also mentions that callers can use
`ArrowBuf#capacity(long)` to set the capacity to the requested size when
needed.

Documentation-only change; no code or behavioral changes.

Closes #141.

Author: axreldable

memory/memory-core/src/main/java/org/apache/arrow/memory/ArrowBuf.java

@@ -136,7 +136,7 @@ public long capacity() {
   /**
    * Adjusts the capacity of this buffer. Size increases are NOT supported.
    *
-   * @param newCapacity Must be in in the range [0, length).
+   * @param newCapacity Must be in the range [0, length).
    */
   public synchronized ArrowBuf capacity(long newCapacity) {
 

memory/memory-core/src/main/java/org/apache/arrow/memory/BufferAllocator.java

@@ -25,9 +25,10 @@
 public interface BufferAllocator extends AutoCloseable {
 
   /**
-   * Allocate a new or reused buffer of the provided size. Note that the buffer may technically be
-   * larger than the requested size for rounding purposes. However, the buffer's capacity will be
-   * set to the configured size.
+   * Allocate a new or reused buffer of the provided size. The buffer may be larger than the
+   * requested size for rounding purposes (e.g. to a power of two), and the buffer's capacity will
+   * reflect the actual allocated size. Use {@link ArrowBuf#capacity(long)} to set the capacity to
+   * the requested size if needed.
    *
    * @param size The size in bytes.
    * @return a new ArrowBuf, or null if the request can't be satisfied
@@ -36,9 +37,10 @@ public interface BufferAllocator extends AutoCloseable {
   ArrowBuf buffer(long size);
 
   /**
-   * Allocate a new or reused buffer of the provided size. Note that the buffer may technically be
-   * larger than the requested size for rounding purposes. However, the buffer's capacity will be
-   * set to the configured size.
+   * Allocate a new or reused buffer of the provided size. The buffer may be larger than the
+   * requested size for rounding purposes (e.g. to a power of two), and the buffer's capacity will
+   * reflect the actual allocated size. Use {@link ArrowBuf#capacity(long)} to set the capacity to
+   * the requested size if needed.
    *
    * @param size The size in bytes.
    * @param manager A buffer manager to manage reallocation.