harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r768919 [2/7] - in /harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio: ./ channels/ channels/spi/
Date Mon, 27 Apr 2009 10:23:38 GMT
Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/CharBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/CharBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/CharBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/CharBuffer.java Mon Apr 27 10:23:36 2009
@@ -20,9 +20,9 @@
 import java.io.IOException;
 
 /**
- * A buffer of <code>char</code>s.
+ * A buffer of chars.
  * <p>
- * A char buffer can be created in either of the following ways:
+ * A char buffer can be created in either one of the following ways:
  * <ul>
  * <li>{@link #allocate(int) Allocate} a new char array and create a buffer
  * based on it;</li>
@@ -33,20 +33,18 @@
  * <li>Use {@link java.nio.ByteBuffer#asCharBuffer() ByteBuffer.asCharBuffer}
  * to create a char buffer based on a byte buffer.</li>
  * </ul>
- * </p>
- * 
  */
 public abstract class CharBuffer extends Buffer implements
         Comparable<CharBuffer>, CharSequence, Appendable, Readable {
 
     /**
-     * Creates a char buffer based on a new allocated char array.
+     * Creates a char buffer based on a newly allocated char array.
      * 
      * @param capacity
-     *            The capacity of the new buffer
-     * @return The created char buffer
+     *            the capacity of the new buffer.
+     * @return the created char buffer.
      * @throws IllegalArgumentException
-     *             If <code>capacity</code> is less than zero
+     *             if {@code capacity} is less than zero.
      */
     public static CharBuffer allocate(int capacity) {
         if (capacity < 0) {
@@ -59,36 +57,33 @@
      * Creates a new char buffer by wrapping the given char array.
      * <p>
      * Calling this method has the same effect as
-     * <code>wrap(array, 0, array.length)</code>.
-     * </p>
-     * 
+     * {@code wrap(array, 0, array.length)}.
+     *
      * @param array
-     *            The char array which the new buffer will be based on
-     * @return The created char buffer
+     *            the char array which the new buffer will be based on.
+     * @return the created char buffer.
      */
     public static CharBuffer wrap(char[] array) {
         return wrap(array, 0, array.length);
     }
 
     /**
-     * Creates new a char buffer by wrapping the given char array.
+     * Creates a new char buffer by wrapping the given char array.
      * <p>
-     * The new buffer's position will be <code>start</code>, limit will be
-     * <code>start + len</code>, capacity will be the length of the array.
-     * </p>
-     * 
+     * The new buffer's position will be {@code start}, limit will be
+     * {@code start + len}, capacity will be the length of the array.
+     *
      * @param array
-     *            The char array which the new buffer will be based on
+     *            the char array which the new buffer will be based on.
      * @param start
-     *            The start index, must be no less than zero and no greater than
-     *            <code>array.length</code>
+     *            the start index, must not be negative and not greater than
+     *            {@code array.length}.
      * @param len
-     *            The length, must be no less than zero and no greater than
-     *            <code>array.length - start</code>
-     * @return The created char buffer
+     *            the length, must not be negative and not greater than
+     *            {@code array.length - start}.
+     * @return the created char buffer.
      * @exception IndexOutOfBoundsException
-     *                If either <code>start</code> or <code>len</code> is
-     *                invalid
+     *                if either {@code start} or {@code len} is invalid.
      */
     public static CharBuffer wrap(char[] array, int start, int len) {
         int length = array.length;
@@ -107,12 +102,11 @@
      * Creates a new char buffer by wrapping the given char sequence.
      * <p>
      * Calling this method has the same effect as
-     * <code>wrap(chseq, 0, chseq.length())</code>.
-     * </p>
-     * 
+     * {@code wrap(chseq, 0, chseq.length())}.
+     *
      * @param chseq
-     *            The char sequence which the new buffer will be based on
-     * @return The created char buffer
+     *            the char sequence which the new buffer will be based on.
+     * @return the created char buffer.
      */
     public static CharBuffer wrap(CharSequence chseq) {
         return BufferFactory.newCharBuffer(chseq);
@@ -121,23 +115,21 @@
     /**
      * Creates a new char buffer by wrapping the given char sequence.
      * <p>
-     * The new buffer's position will be <code>start</code>, limit will be
-     * <code>end</code>, capacity will be the length of the char sequence.
-     * The new buffer is readonly.
-     * </p>
-     * 
+     * The new buffer's position will be {@code start}, limit will be
+     * {@code end}, capacity will be the length of the char sequence. The new
+     * buffer is read-only.
+     *
      * @param chseq
-     *            The char sequence which the new buffer will be based on
+     *            the char sequence which the new buffer will be based on.
      * @param start
-     *            The start index, must be no less than zero and no greater than
-     *            <code>chseq.length()</code>
+     *            the start index, must not be negative and not greater than
+     *            {@code chseq.length()}.
      * @param end
-     *            The end index, must be no less than <code>start</code> and
-     *            no greater than <code>chseq.length()</code>
-     * @return The created char buffer
+     *            the end index, must be no less than {@code start} and no
+     *            greater than {@code chseq.length()}.
+     * @return the created char buffer.
      * @exception IndexOutOfBoundsException
-     *                If either <code>start</code> or <code>end</code> is
-     *                invalid
+     *                if either {@code start} or {@code end} is invalid.
      */
     public static CharBuffer wrap(CharSequence chseq, int start, int end) {
         if (chseq == null) {
@@ -154,23 +146,23 @@
     }
 
     /**
-     * Constructs a <code>CharBuffer</code> with given capacity.
+     * Constructs a {@code CharBuffer} with given capacity.
      * 
      * @param capacity
-     *            The capacity of the buffer
+     *            the capacity of the buffer.
      */
     CharBuffer(int capacity) {
         super(capacity);
     }
 
     /**
-     * Returns the char array which this buffer is based on, if there's one.
+     * Returns the char array which this buffer is based on, if there is one.
      * 
-     * @return The char array which this buffer is based on
+     * @return the char array which this buffer is based on.
      * @exception ReadOnlyBufferException
-     *                If this buffer is based on an array, but it is readonly
+     *                if this buffer is based on an array, but it is read-only.
      * @exception UnsupportedOperationException
-     *                If this buffer is not based on an array
+     *                if this buffer is not based on an array.
      */
     public final char[] array() {
         return protectedArray();
@@ -178,36 +170,33 @@
 
     /**
      * Returns the offset of the char array which this buffer is based on, if
-     * there's one.
+     * there is one.
      * <p>
      * The offset is the index of the array corresponds to the zero position of
      * the buffer.
-     * </p>
-     * 
-     * @return The offset of the char array which this buffer is based on
+     *
+     * @return the offset of the char array which this buffer is based on.
      * @exception ReadOnlyBufferException
-     *                If this buffer is based on an array, but it is readonly
+     *                if this buffer is based on an array but it is read-only.
      * @exception UnsupportedOperationException
-     *                If this buffer is not based on an array
+     *                if this buffer is not based on an array.
      */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
     /**
-     * Returns a readonly buffer that shares content with this buffer.
+     * Returns a read-only buffer that shares its content with this buffer.
      * <p>
-     * The returned buffer is guaranteed to be a new instance, even this buffer
-     * is readonly itself. The new buffer's position, limit, capacity and mark
-     * are the same as this buffer.
-     * </p>
-     * <p>
-     * The new buffer shares content with this buffer, which means this buffer's
-     * change of content will be visible to the new buffer. The two buffer's
-     * position, limit and mark are independent.
-     * </p>
-     * 
-     * @return A readonly version of this buffer.
+     * The returned buffer is guaranteed to be a new instance, even if this
+     * buffer is read-only itself. The new buffer's position, limit, capacity
+     * and mark are the same as this buffer's.
+     * <p>
+     * The new buffer shares its content with this buffer, which means this
+     * buffer's change of content will be visible to the new buffer. The two
+     * buffer's position, limit and mark are independent.
+     *
+     * @return a read-only version of this buffer.
      */
     public abstract CharBuffer asReadOnlyBuffer();
 
@@ -216,13 +205,13 @@
      * index value is referenced from the current buffer position.
      * 
      * @param index
-     *            The index referenced from the current buffer position. It must
+     *            the index referenced from the current buffer position. It must
      *            not be less than zero but less than the value obtained from a
-     *            call to <code>remaining()</code>
+     *            call to {@code remaining()}.
      * @return the character located at the specified index (referenced from the
      *         current position) in the buffer.
      * @exception IndexOutOfBoundsException
-     *                If the index is invalid
+     *                if the index is invalid.
      */
     public final char charAt(int index) {
         if (index < 0 || index >= remaining()) {
@@ -234,29 +223,27 @@
     /**
      * Compacts this char buffer.
      * <p>
-     * The remaining <code>char</code>s will be moved to the head of the
-     * buffer, staring from position zero. Then the position is set to
-     * <code>remaining()</code>; the limit is set to capacity; the mark is
-     * cleared.
-     * </p>
-     * 
-     * @return This buffer
+     * The remaining chars will be moved to the head of the buffer,
+     * starting from position zero. Then the position is set to
+     * {@code remaining()}; the limit is set to capacity; the mark is cleared.
+     *
+     * @return this buffer.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public abstract CharBuffer compact();
 
     /**
-     * Compare the remaining <code>char</code>s of this buffer to another
-     * char buffer's remaining <code>char</code>s.
+     * Compare the remaining chars of this buffer to another char
+     * buffer's remaining chars.
      * 
      * @param otherBuffer
-     *            Another char buffer
-     * @return a negative value if this is less than <code>other</code>; 0 if
-     *         this equals to <code>other</code>; a positive value if this is
-     *         greater than <code>other</code>
+     *            another char buffer.
+     * @return a negative value if this is less than {@code otherBuffer}; 0 if
+     *         this equals to {@code otherBuffer}; a positive value if this is
+     *         greater than {@code otherBuffer}.
      * @exception ClassCastException
-     *                If <code>other</code> is not a char buffer
+     *                if {@code otherBuffer} is not a char buffer.
      */
     public int compareTo(CharBuffer otherBuffer) {
         int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -278,36 +265,31 @@
     }
 
     /**
-     * Returns a duplicated buffer that shares content with this buffer.
+     * Returns a duplicated buffer that shares its content with this buffer.
      * <p>
-     * The duplicated buffer's position, limit, capacity and mark are the same
-     * as this buffer. The duplicated buffer's readonly property and byte order
-     * are same as this buffer too.
-     * </p>
+     * The duplicated buffer's initial position, limit, capacity and mark are
+     * the same as this buffer's. The duplicated buffer's read-only property and
+     * byte order are the same as this buffer's, too.
      * <p>
-     * The new buffer shares content with this buffer, which means either
+     * The new buffer shares its content with this buffer, which means either
      * buffer's change of content will be visible to the other. The two buffer's
      * position, limit and mark are independent.
-     * </p>
-     * 
-     * @return A duplicated buffer that shares content with this buffer.
+     *
+     * @return a duplicated buffer that shares its content with this buffer.
      */
     public abstract CharBuffer duplicate();
 
     /**
-     * Tests whether this char buffer equals to another object.
+     * Checks whether this char buffer is equal to another object.
      * <p>
-     * If <code>other</code> is not a char buffer, then false is returned.
-     * </p>
-     * <p>
-     * Two char buffers are equals if, and only if, their remaining
-     * <code>char</code>s are exactly the same. Position, limit, capacity and
-     * mark are not considered.
-     * </p>
-     * 
+     * If {@code other} is not a char buffer then {@code false} is returned. Two
+     * char buffers are equal if and only if their remaining chars are exactly
+     * the same. Position, limit, capacity and mark are not considered.
+     *
      * @param other
-     *            the object to be compared against
-     * @return Whether this char buffer equals to another object.
+     *            the object to compare with this char buffer.
+     * @return {@code true} if this char buffer is equal to {@code other},
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object other) {
@@ -331,54 +313,49 @@
     }
 
     /**
-     * Returns the char at the current position and increase the position by 1.
+     * Returns the char at the current position and increases the position by 1.
      * 
-     * @return The char at the current position.
+     * @return the char at the current position.
      * @exception BufferUnderflowException
-     *                If the position is equal or greater than limit
+     *                if the position is equal or greater than limit.
      */
     public abstract char get();
 
     /**
-     * Reads <code>char</code>s from the current position into the specified
-     * char array and increase the position by the number of <code>char</code>s
-     * read.
+     * Reads chars from the current position into the specified char array and
+     * increases the position by the number of chars read.
      * <p>
      * Calling this method has the same effect as
-     * <code>get(dest, 0, dest.length)</code>.
-     * </p>
-     * 
+     * {@code get(dest, 0, dest.length)}.
+     *
      * @param dest
-     *            The destination char array
-     * @return This buffer
+     *            the destination char array.
+     * @return this buffer.
      * @exception BufferUnderflowException
-     *                if <code>dest.length</code> is greater than
-     *                <code>remaining()</code>
+     *                if {@code dest.length} is greater than {@code remaining()}.
      */
     public CharBuffer get(char[] dest) {
         return get(dest, 0, dest.length);
     }
 
     /**
-     * Reads <code>char</code>s from the current position into the specified
-     * char array, starting from the specified offset, and increase the position
-     * by the number of <code>char</code>s read.
+     * Reads chars from the current position into the specified char array,
+     * starting from the specified offset, and increases the position by the
+     * number of chars read.
      * 
      * @param dest
-     *            The target char array
+     *            the target char array.
      * @param off
-     *            The offset of the char array, must be no less than zero and no
-     *            greater than <code>dest.length</code>
+     *            the offset of the char array, must not be negative and not
+     *            greater than {@code dest.length}.
      * @param len
-     *            The number of <code>char</code>s to read, must be no less
-     *            than zero and no greater than <code>dest.length - off</code>
-     * @return This buffer
+     *            The number of chars to read, must be no less than zero and no
+     *            greater than {@code dest.length - off}.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If either <code>off</code> or <code>len</code> is
-     *                invalid
+     *                if either {@code off} or {@code len} is invalid.
      * @exception BufferUnderflowException
-     *                If <code>len</code> is greater than
-     *                <code>remaining()</code>
+     *                if {@code len} is greater than {@code remaining()}.
      */
     public CharBuffer get(char[] dest, int off, int len) {
         int length = dest.length;
@@ -396,35 +373,31 @@
     }
 
     /**
-     * Returns a char at the specified index, and the position is not changed.
+     * Returns a char at the specified index; the position is not changed.
      * 
      * @param index
-     *            The index, must be no less than zero and less than limit
-     * @return A char at the specified index.
+     *            the index, must not be negative and less than limit.
+     * @return a char at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      */
     public abstract char get(int index);
 
     /**
-     * Returns whether this buffer is based on a char array and is read/write.
-     * <p>
-     * If this buffer is readonly, then false is returned.
-     * </p>
-     * 
-     * @return Whether this buffer is based on a char array and is read/write.
+     * Indicates whether this buffer is based on a char array and is read/write.
+     *
+     * @return {@code true} if this buffer is based on a byte array and provides
+     *         read/write access, {@code false} otherwise.
      */
     public final boolean hasArray() {
         return protectedHasArray();
     }
 
     /**
-     * Hash code is calculated from the remaining <code>char</code>s.
-     * <p>
-     * Position, limit, capacity and mark don't affect the hash code.
-     * </p>
-     * 
-     * @return The hash code calculated from the remaining <code>char</code>s.
+     * Calculates this buffer's hash code from the remaining chars. The
+     * position, limit, capacity and mark don't affect the hash code.
+     *
+     * @return the hash code calculated from the remaining chars.
      */
     @Override
     public int hashCode() {
@@ -437,121 +410,112 @@
     }
 
     /**
-     * Returns true if this buffer is direct.
-     * <p>
-     * A direct buffer will try its best to take advantage of native memory APIs
-     * and it may not stay in java heap, thus not affected by GC.
-     * </p>
+     * Indicates whether this buffer is direct. A direct buffer will try its
+     * best to take advantage of native memory APIs and it may not stay in the
+     * Java heap, so it is not affected by garbage collection.
      * <p>
-     * A char buffer is direct, if it is based on a byte buffer and the byte
+     * A char buffer is direct if it is based on a byte buffer and the byte
      * buffer is direct.
-     * </p>
-     * 
-     * @return True if this buffer is direct.
+     *
+     * @return {@code true} if this buffer is direct, {@code false} otherwise.
      */
     public abstract boolean isDirect();
 
     /**
-     * Returns the number of remaining <code>char</code>s.
+     * Returns the number of remaining chars.
      * 
-     * @return The number of remaining <code>char</code>s.
+     * @return the number of remaining chars.
      */
     public final int length() {
         return remaining();
     }
 
     /**
-     * Returns the byte order used by this buffer when converting
-     * <code>char</code>s from/to <code>byte</code>s.
+     * Returns the byte order used by this buffer when converting chars from/to
+     * bytes.
      * <p>
-     * If this buffer is not based on a byte buffer, then always return the
-     * platform's native byte order.
-     * </p>
-     * 
-     * @return The byte order used by this buffer when converting
-     *         <code>char</code>s from/to <code>byte</code>s.
+     * If this buffer is not based on a byte buffer, then this always returns
+     * the platform's native byte order.
+     *
+     * @return the byte order used by this buffer when converting chars from/to
+     *         bytes.
      */
     public abstract ByteOrder order();
 
     /**
-     * Child class implements this method to realize <code>array()</code>.
-     * 
-     * @return see <code>array()</code>
+     * Child class implements this method to realize {@code array()}.
+     *
+     * @see #array()
      */
     abstract char[] protectedArray();
 
     /**
-     * Child class implements this method to realize <code>arrayOffset()</code>.
-     * 
-     * @return see <code>arrayOffset()</code>
+     * Child class implements this method to realize {@code arrayOffset()}.
+     *
+     * @see #arrayOffset()
      */
     abstract int protectedArrayOffset();
 
     /**
-     * Child class implements this method to realize <code>hasArray()</code>.
-     * 
-     * @return see <code>hasArray()</code>
+     * Child class implements this method to realize {@code hasArray()}.
+     *
+     * @see #hasArray()
      */
     abstract boolean protectedHasArray();
 
     /**
-     * Writes the given char to the current position and increase the position
+     * Writes the given char to the current position and increases the position
      * by 1.
      * 
      * @param c
-     *            The char to write
-     * @return This buffer
+     *            the char to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is equal or greater than limit
+     *                if position is equal or greater than limit.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public abstract CharBuffer put(char c);
 
     /**
-     * Writes <code>char</code>s in the given char array to the current
-     * position and increase the position by the number of <code>char</code>s
-     * written.
+     * Writes chars from the given char array to the current position and
+     * increases the position by the number of chars written.
      * <p>
      * Calling this method has the same effect as
-     * <code>put(src, 0, src.length)</code>.
-     * </p>
-     * 
+     * {@code put(src, 0, src.length)}.
+     *
      * @param src
-     *            The source char array
-     * @return This buffer
+     *            the source char array.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>remaining()</code> is less than
-     *                <code>src.length</code>
+     *                if {@code remaining()} is less than {@code src.length}.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public final CharBuffer put(char[] src) {
         return put(src, 0, src.length);
     }
 
     /**
-     * Writes <code>char</code>s in the given char array, starting from the
-     * specified offset, to the current position and increase the position by
-     * the number of <code>char</code>s written.
+     * Writes chars from the given char array, starting from the specified offset,
+     * to the current position and increases the position by the number of chars
+     * written.
      * 
      * @param src
-     *            The source char array
+     *            the source char array.
      * @param off
-     *            The offset of char array, must be no less than zero and no
-     *            greater than <code>src.length</code>
+     *            the offset of char array, must not be negative and not greater
+     *            than {@code src.length}.
      * @param len
-     *            The number of <code>char</code>s to write, must be no less
-     *            than zero and no greater than <code>src.length - off</code>
-     * @return This buffer
+     *            the number of chars to write, must be no less than zero and no
+     *            greater than {@code src.length - off}.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>remaining()</code> is less than
-     *                <code>len</code>
+     *                if {@code remaining()} is less than {@code len}.
      * @exception IndexOutOfBoundsException
-     *                If either <code>off</code> or <code>len</code> is
-     *                invalid
+     *                if either {@code off} or {@code len} is invalid.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public CharBuffer put(char[] src, int off, int len) {
         int length = src.length;
@@ -569,20 +533,20 @@
     }
 
     /**
-     * Writes all the remaining <code>char</code>s of the <code>src</code>
-     * char buffer to this buffer's current position, and increase both buffers'
-     * position by the number of <code>char</code>s copied.
+     * Writes all the remaining chars of the {@code src} char buffer to this
+     * buffer's current position, and increases both buffers' position by the
+     * number of chars copied.
      * 
      * @param src
-     *            The source char buffer
-     * @return This buffer
+     *            the source char buffer.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>src.remaining()</code> is greater than this
-     *                buffer's <code>remaining()</code>
+     *                if {@code src.remaining()} is greater than this buffer's
+     *                {@code remaining()}.
      * @exception IllegalArgumentException
-     *                If <code>src</code> is this buffer
+     *                if {@code src} is this buffer.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public CharBuffer put(CharBuffer src) {
         if (src == this) {
@@ -599,66 +563,59 @@
     }
 
     /**
-     * Write a char to the specified index of this buffer and the position is
-     * not changed.
+     * Writes a char to the specified index of this buffer; the position is not
+     * changed.
      * 
      * @param index
-     *            The index, must be no less than zero and less than the limit
+     *            the index, must be no less than zero and less than the limit.
      * @param c
-     *            The char to write
-     * @return This buffer
+     *            the char to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public abstract CharBuffer put(int index, char c);
 
     /**
-     * Write all <code>char</code>s of the give string to the current
-     * position of this buffer, and increase the position by the length of
-     * string.
+     * Writes all chars of the given string to the current position of this
+     * buffer, and increases the position by the length of string.
      * <p>
      * Calling this method has the same effect as
-     * <code>put(str, 0, str.length())</code>.
-     * </p>
-     * 
+     * {@code put(str, 0, str.length())}.
+     *
      * @param str
-     *            The string to write
-     * @return This buffer
+     *            the string to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>remaining()</code> is less than the length of
-     *                string
+     *                if {@code remaining()} is less than the length of string.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public final CharBuffer put(String str) {
         return put(str, 0, str.length());
     }
 
     /**
-     * Write <code>char</code>s of the given string to the current position
-     * of this buffer, and increase the position by the number of
-     * <code>char</code>s written.
+     * Writes chars of the given string to the current position of this buffer,
+     * and increases the position by the number of chars written.
      * 
      * @param str
-     *            The string to write
+     *            the string to write.
      * @param start
-     *            The first char to write, must be no less than zero and no
-     *            greater than <code>str.length()</code>
+     *            the first char to write, must not be negative and not greater
+     *            than {@code str.length()}.
      * @param end
-     *            The last char to write (excluding), must be less than
-     *            <code>start</code> and no greater than
-     *            <code>str.length()</code>
-     * @return This buffer
+     *            the last char to write (excluding), must be less than
+     *            {@code start} and not greater than {@code str.length()}.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>remaining</code> is less than
-     *                <code>end - start</code>
+     *                if {@code remaining()} is less than {@code end - start}.
      * @exception IndexOutOfBoundsException
-     *                If either <code>start</code> or <code>end</code> is
-     *                invalid
+     *                if either {@code start} or {@code end} is invalid.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public CharBuffer put(String str, int start, int end) {
         int length = str.length();
@@ -676,63 +633,56 @@
     }
 
     /**
-     * Returns a sliced buffer that shares content with this buffer.
+     * Returns a sliced buffer that shares its content with this buffer.
      * <p>
-     * The sliced buffer's capacity will be this buffer's
-     * <code>remaining()</code>, and its zero position will correspond to
-     * this buffer's current position. The new buffer's position will be 0,
-     * limit will be its capacity, and its mark is unset. The new buffer's
-     * readonly property and byte order are same as this buffer.
-     * </p>
+     * The sliced buffer's capacity will be this buffer's {@code remaining()},
+     * and its zero position will correspond to this buffer's current position.
+     * The new buffer's position will be 0, limit will be its capacity, and its
+     * mark is cleared. The new buffer's read-only property and byte order are
+     * same as this buffer.
      * <p>
-     * The new buffer shares content with this buffer, which means either
+     * The new buffer shares its content with this buffer, which means either
      * buffer's change of content will be visible to the other. The two buffer's
      * position, limit and mark are independent.
-     * </p>
-     * 
-     * @return A sliced buffer that shares content with this buffer.
+     *
+     * @return a sliced buffer that shares its content with this buffer.
      */
     public abstract CharBuffer slice();
 
     /**
-     * Returns a new char buffer represents a sub-sequence of this buffer's
+     * Returns a new char buffer representing a sub-sequence of this buffer's
      * current remaining content.
      * <p>
-     * The new buffer's position will be <code>position() + start</code>,
-     * limit will be <code>position() + end</code>, capacity will be same as
-     * this buffer. The new buffer's readonly property and byte order are same
-     * as this buffer.
-     * </p>
+     * The new buffer's position will be {@code position() + start}, limit will
+     * be {@code position() + end}, capacity will be the same as this buffer.
+     * The new buffer's read-only property and byte order are the same as this
+     * buffer.
      * <p>
-     * The new buffer shares content with this buffer, which means either
+     * The new buffer shares its content with this buffer, which means either
      * buffer's change of content will be visible to the other. The two buffer's
      * position, limit and mark are independent.
-     * </p>
-     * 
+     *
      * @param start
-     *            The start index of the sub-sequence, referenced from the
+     *            the start index of the sub-sequence, referenced from the
      *            current buffer position. Must not be less than zero and not
      *            greater than the value obtained from a call to
-     *            <code>remaining()</code>.
+     *            {@code remaining()}.
      * @param end
-     *            The end index of the sub-sequence, referenced from the current
-     *            buffer position. Must not be less than <code>start</code>
-     *            and not be greater than the value obtained from a call to
-     *            <code>remaining()</code>
-     * @return A new char buffer represents a sub-sequence of this buffer's
+     *            the end index of the sub-sequence, referenced from the current
+     *            buffer position. Must not be less than {@code start} and not
+     *            be greater than the value obtained from a call to
+     *            {@code remaining()}.
+     * @return a new char buffer represents a sub-sequence of this buffer's
      *         current remaining content.
      * @exception IndexOutOfBoundsException
-     *                If either <code>start</code> or <code>end</code> is
-     *                invalid
+     *                if either {@code start} or {@code end} is invalid.
      */
     public abstract CharSequence subSequence(int start, int end);
 
     /**
-     * Returns a string represents the current remaining <code>char</code>s
-     * of this buffer.
+     * Returns a string representing the current remaining chars of this buffer.
      * 
-     * @return A string represents the current remaining <code>char</code>s
-     *         of this buffer.
+     * @return a string representing the current remaining chars of this buffer.
      */
     @Override
     public String toString() {
@@ -744,14 +694,37 @@
     }
 
     /**
-     * @see Appendable#append(char)
+     * Writes the given char to the current position and increases the position
+     * by 1.
+     *
+     * @param c
+     *            the char to write.
+     * @return this buffer.
+     * @exception BufferOverflowException
+     *                if position is equal or greater than limit.
+     * @exception ReadOnlyBufferException
+     *                if no changes may be made to the contents of this buffer.
      */
     public CharBuffer append(char c) {
         return put(c);
     }
 
     /**
-     * @see Appendable#append(CharSequence)
+     * Writes all chars of the given character sequence {@code csq} to the
+     * current position of this buffer, and increases the position by the length
+     * of the csq.
+     * <p>
+     * Calling this method has the same effect as {@code append(csq.toString())}.
+     * If the {@code CharSequence} is {@code null} the string "null" will be
+     * written to the buffer.
+     *
+     * @param csq
+     *            the {@code CharSequence} to write.
+     * @return this buffer.
+     * @exception BufferOverflowException
+     *                if {@code remaining()} is less than the length of csq.
+     * @exception ReadOnlyBufferException
+     *                if no changes may be made to the contents of this buffer.
      */
     public CharBuffer append(CharSequence csq) {
         if (csq != null) {
@@ -761,7 +734,24 @@
     }
 
     /**
-     * @see Appendable#append(CharSequence, int, int)
+     * Writes chars of the given {@code CharSequence} to the current position of
+     * this buffer, and increases the position by the number of chars written.
+     *
+     * @param csq
+     *            the {@code CharSequence} to write.
+     * @param start
+     *            the first char to write, must not be negative and not greater
+     *            than {@code csq.length()}.
+     * @param end
+     *            the last char to write (excluding), must be less than
+     *            {@code start} and not greater than {@code csq.length()}.
+     * @return this buffer.
+     * @exception BufferOverflowException
+     *                if {@code remaining()} is less than {@code end - start}.
+     * @exception IndexOutOfBoundsException
+     *                if either {@code start} or {@code end} is invalid.
+     * @exception ReadOnlyBufferException
+     *                if no changes may be made to the contents of this buffer.
      */
     public CharBuffer append(CharSequence csq, int start, int end) {
         if (csq == null) {
@@ -775,7 +765,21 @@
     }
 
     /**
-     * @see Readable#read(CharBuffer)
+     * Reads characters from this buffer and puts them into {@code target}. The
+     * number of chars that are copied is either the number of remaining chars
+     * in this buffer or the number of remaining chars in {@code target},
+     * whichever is smaller.
+     *
+     * @param target
+     *            the target char buffer.
+     * @throws IllegalArgumentException
+     *             if {@code target} is this buffer.
+     * @throws IOException
+     *             if an I/O error occurs.
+     * @throws ReadOnlyBufferException
+     *             if no changes may be made to the contents of {@code target}.
+     * @return the number of chars copied or -1 if there are no chars left to be
+     *         read from this buffer.
      */
     public int read(CharBuffer target) throws IOException {
         if (target == this) {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DirectByteBuffers.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DirectByteBuffers.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DirectByteBuffers.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DirectByteBuffers.java Mon Apr 27 10:23:36 2009
@@ -31,13 +31,11 @@
      * If the memory is known to already have been freed then this is a no-op.
      * Once the memory has been freed then operations requiring access to the
      * memory will throw an <code>IllegalStateException</code>.
-     * </p>
      * <p>
      * Note this is is possible that the memory is freed by code that reaches
      * into the address and explicitly frees it 'beneith' us -- this is bad
      * form.
-     * </p>
-     * 
+     *
      * @param directBuffer
      *            the direct byte buffer memory to free
      * @throws IllegalArgumentException
@@ -53,7 +51,7 @@
     }
 
     /**
-     * Answers the platform address of the start of this buffer instance.
+     * Returns the platform address of the start of this buffer instance.
      * <em>You must not attempt to free the returned address!!</em> It may not
      * be an address that was explicitly malloc'ed (i.e. if this buffer is the
      * result of a split); and it may be memory shared by multiple buffers.
@@ -61,8 +59,7 @@
      * If you can guarantee that you want to free the underlying memory call the
      * #free() method on this instance -- generally applications will rely on
      * the garbage collector to autofree this memory.
-     * </p>
-     * 
+     *
      * @param directBuffer
      *            the direct byte buffer
      * @return the effective address of the start of the buffer.

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DoubleBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DoubleBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DoubleBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DoubleBuffer.java Mon Apr 27 10:23:36 2009
@@ -18,9 +18,9 @@
 package java.nio;
 
 /**
- * A buffer of <code>double</code>s.
+ * A buffer of doubles.
  * <p>
- * A double buffer can be created in either of the following ways:
+ * A double buffer can be created in either one of the following ways:
  * <ul>
  * <li>{@link #allocate(int) Allocate} a new double array and create a buffer
  * based on it;</li>
@@ -30,19 +30,18 @@
  * {@link java.nio.ByteBuffer#asDoubleBuffer() ByteBuffer.asDoubleBuffer} to
  * create a double buffer based on a byte buffer.</li>
  * </ul>
- * </p>
  */
 public abstract class DoubleBuffer extends Buffer implements
         Comparable<DoubleBuffer> {
 
     /**
-     * Creates a double buffer based on a new allocated double array.
+     * Creates a double buffer based on a newly allocated double array.
      * 
      * @param capacity
-     *            The capacity of the new buffer
-     * @return The created double buffer
+     *            the capacity of the new buffer.
+     * @return the created double buffer.
      * @throws IllegalArgumentException
-     *             If <code>capacity</code> is less than zero
+     *             if {@code capacity} is less than zero.
      */
     public static DoubleBuffer allocate(int capacity) {
         if (capacity < 0) {
@@ -55,36 +54,33 @@
      * Creates a new double buffer by wrapping the given double array.
      * <p>
      * Calling this method has the same effect as
-     * <code>wrap(array, 0, array.length)</code>.
-     * </p>
-     * 
+     * {@code wrap(array, 0, array.length)}.
+     *
      * @param array
-     *            The double array which the new buffer will be based on
-     * @return The created double buffer
+     *            the double array which the new buffer will be based on.
+     * @return the created double buffer.
      */
     public static DoubleBuffer wrap(double[] array) {
         return wrap(array, 0, array.length);
     }
 
     /**
-     * Creates new a double buffer by wrapping the given double array.
+     * Creates a new double buffer by wrapping the given double array.
      * <p>
-     * The new buffer's position will be <code>start</code>, limit will be
-     * <code>start + len</code>, capacity will be the length of the array.
-     * </p>
-     * 
+     * The new buffer's position will be {@code start}, limit will be
+     * {@code start + len}, capacity will be the length of the array.
+     *
      * @param array
-     *            The double array which the new buffer will be based on
+     *            the double array which the new buffer will be based on.
      * @param start
-     *            The start index, must be no less than zero and no greater than
-     *            <code>array.length</code>
+     *            the start index, must not be negative and not greater than
+     *            {@code array.length}.
      * @param len
-     *            The length, must be no less than zero and no greater than
-     *            <code>array.length - start</code>
-     * @return The created double buffer
+     *            the length, must not be negative and not greater than
+     *            {@code array.length - start}.
+     * @return the created double buffer.
      * @exception IndexOutOfBoundsException
-     *                If either <code>start</code> or <code>len</code> is
-     *                invalid
+     *                if either {@code start} or {@code len} is invalid.
      */
     public static DoubleBuffer wrap(double[] array, int start, int len) {
         int length = array.length;
@@ -100,23 +96,23 @@
     }
 
     /**
-     * Constructs a <code>DoubleBuffer</code> with given capacity.
+     * Constructs a {@code DoubleBuffer} with given capacity.
      * 
      * @param capacity
-     *            The capacity of the buffer
+     *            the capacity of the buffer.
      */
     DoubleBuffer(int capacity) {
         super(capacity);
     }
 
     /**
-     * Returns the double array which this buffer is based on, if there's one.
+     * Returns the double array which this buffer is based on, if there is one.
      * 
-     * @return The double array which this buffer is based on
+     * @return the double array which this buffer is based on.
      * @exception ReadOnlyBufferException
-     *                If this buffer is based on an array, but it is readonly
+     *                if this buffer is based on an array but it is read-only.
      * @exception UnsupportedOperationException
-     *                If this buffer is not based on an array
+     *                if this buffer is not based on an array.
      */
     public final double[] array() {
         return protectedArray();
@@ -124,65 +120,60 @@
 
     /**
      * Returns the offset of the double array which this buffer is based on, if
-     * there's one.
+     * there is one.
      * <p>
-     * The offset is the index of the array corresponds to the zero position of
-     * the buffer.
-     * </p>
-     * 
-     * @return The offset of the double array which this buffer is based on
+     * The offset is the index of the array corresponding to the zero position
+     * of the buffer.
+     *
+     * @return the offset of the double array which this buffer is based on.
      * @exception ReadOnlyBufferException
-     *                If this buffer is based on an array, but it is readonly
+     *                if this buffer is based on an array, but it is read-only.
      * @exception UnsupportedOperationException
-     *                If this buffer is not based on an array
+     *                if this buffer is not based on an array.
      */
     public final int arrayOffset() {
         return protectedArrayOffset();
     }
 
     /**
-     * Returns a readonly buffer that shares content with this buffer.
-     * <p>
-     * The returned buffer is guaranteed to be a new instance, even this buffer
-     * is readonly itself. The new buffer's position, limit, capacity and mark
-     * are the same as this buffer.
-     * </p>
+     * Returns a read-only buffer that shares its content with this buffer.
      * <p>
-     * The new buffer shares content with this buffer, which means this buffer's
-     * change of content will be visible to the new buffer. The two buffer's
-     * position, limit and mark are independent.
-     * </p>
-     * 
-     * @return A readonly version of this buffer.
+     * The returned buffer is guaranteed to be a new instance, even if this
+     * buffer is read-only itself. The new buffer's position, limit, capacity
+     * and mark are the same as this buffer's.
+     * <p>
+     * The new buffer shares its content with this buffer, which means that this
+     * buffer's change of content will be visible to the new buffer. The two
+     * buffer's position, limit and mark are independent.
+     *
+     * @return a read-only version of this buffer.
      */
     public abstract DoubleBuffer asReadOnlyBuffer();
 
     /**
      * Compacts this double buffer.
      * <p>
-     * The remaining <code>double</code>s will be moved to the head of the
-     * buffer, staring from position zero. Then the position is set to
-     * <code>remaining()</code>; the limit is set to capacity; the mark is
-     * cleared.
-     * </p>
-     * 
-     * @return This buffer
+     * The remaining doubles will be moved to the head of the buffer, staring
+     * from position zero. Then the position is set to {@code remaining()}; the
+     * limit is set to capacity; the mark is cleared.
+     *
+     * @return this buffer.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public abstract DoubleBuffer compact();
 
     /**
-     * Compare the remaining <code>double</code>s of this buffer to another
-     * double buffer's remaining <code>double</code>s.
+     * Compare the remaining doubles of this buffer to another double buffer's
+     * remaining doubles.
      * 
      * @param otherBuffer
-     *            Another double buffer
-     * @return a negative value if this is less than <code>other</code>; 0 if
-     *         this equals to <code>other</code>; a positive value if this is
-     *         greater than <code>other</code>
+     *            another double buffer.
+     * @return a negative value if this is less than {@code other}; 0 if this
+     *         equals to {@code other}; a positive value if this is greater
+     *         than {@code other}.
      * @exception ClassCastException
-     *                If <code>other</code> is not a double buffer
+     *                if {@code other} is not a double buffer.
      */
     public int compareTo(DoubleBuffer otherBuffer) {
         int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -206,36 +197,31 @@
     }
 
     /**
-     * Returns a duplicated buffer that shares content with this buffer.
+     * Returns a duplicated buffer that shares its content with this buffer.
      * <p>
      * The duplicated buffer's position, limit, capacity and mark are the same
-     * as this buffer. The duplicated buffer's readonly property and byte order
-     * are same as this buffer too.
-     * </p>
+     * as this buffer's. The duplicated buffer's read-only property and byte
+     * order are the same as this buffer's, too.
      * <p>
-     * The new buffer shares content with this buffer, which means either
+     * The new buffer shares its content with this buffer, which means either
      * buffer's change of content will be visible to the other. The two buffer's
      * position, limit and mark are independent.
-     * </p>
-     * 
-     * @return A duplicated buffer that shares content with this buffer.
+     *
+     * @return a duplicated buffer that shares its content with this buffer.
      */
     public abstract DoubleBuffer duplicate();
 
     /**
-     * Tests whether this double buffer equals to another object.
+     * Checks whether this double buffer is equal to another object.
      * <p>
-     * If <code>other</code> is not a double buffer, then false is returned.
-     * </p>
-     * <p>
-     * Two double buffers are equals if, and only if, their remaining
-     * <code>double</code>s are exactly the same. Position, limit, capacity
-     * and mark are not considered.
-     * </p>
-     * 
+     * If {@code other} is not a double buffer then {@code false} is returned.
+     * Two double buffers are equal if and only if their remaining doubles are
+     * exactly the same. Position, limit, capacity and mark are not considered.
+     *
      * @param other
-     *            the object to be compared against
-     * @return Whether this double buffer equals to another object.
+     *            the object to compare with this double buffer.
+     * @return {@code true} if this double buffer is equal to {@code other},
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object other) {
@@ -259,55 +245,50 @@
     }
 
     /**
-     * Returns the double at the current position and increase the position by
+     * Returns the double at the current position and increases the position by
      * 1.
      * 
-     * @return The double at the current position.
+     * @return the double at the current position.
      * @exception BufferUnderflowException
-     *                If the position is equal or greater than limit
+     *                if the position is equal or greater than limit.
      */
     public abstract double get();
 
     /**
-     * Reads <code>double</code>s from the current position into the
-     * specified double array and increase the position by the number of
-     * <code>double</code>s read.
+     * Reads doubles from the current position into the specified double array
+     * and increases the position by the number of doubles read.
      * <p>
      * Calling this method has the same effect as
-     * <code>get(dest, 0, dest.length)</code>.
-     * </p>
-     * 
+     * {@code get(dest, 0, dest.length)}.
+     *
      * @param dest
-     *            The destination double array
-     * @return This buffer
+     *            the destination double array.
+     * @return this buffer.
      * @exception BufferUnderflowException
-     *                if <code>dest.length</code> is greater than
-     *                <code>remaining()</code>
+     *                if {@code dest.length} is greater than {@code remaining()}.
      */
     public DoubleBuffer get(double[] dest) {
         return get(dest, 0, dest.length);
     }
 
     /**
-     * Reads <code>double</code>s from the current position into the
-     * specified double array, starting from the specified offset, and increase
-     * the position by the number of <code>double</code>s read.
+     * Reads doubles from the current position into the specified double array,
+     * starting from the specified offset, and increases the position by the
+     * number of doubles read.
      * 
      * @param dest
-     *            The target double array
+     *            the target double array.
      * @param off
-     *            The offset of the double array, must be no less than zero and
-     *            no greater than <code>dest.length</code>
+     *            the offset of the double array, must not be negative and not
+     *            greater than {@code dest.length}.
      * @param len
-     *            The number of <code>double</code>s to read, must be no less
-     *            than zero and no greater than <code>dest.length - off</code>
-     * @return This buffer
+     *            the number of doubles to read, must be no less than zero and
+     *            not greater than {@code dest.length - off}.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If either <code>off</code> or <code>len</code> is
-     *                invalid
+     *                if either {@code off} or {@code len} is invalid.
      * @exception BufferUnderflowException
-     *                If <code>len</code> is greater than
-     *                <code>remaining()</code>
+     *                if {@code len} is greater than {@code remaining()}.
      */
     public DoubleBuffer get(double[] dest, int off, int len) {
         int length = dest.length;
@@ -325,35 +306,32 @@
     }
 
     /**
-     * Returns a double at the specified index, and the position is not changed.
+     * Returns a double at the specified index; the position is not changed.
      * 
      * @param index
-     *            The index, must be no less than zero and less than limit
-     * @return A double at the specified index.
+     *            the index, must not be negative and less than limit.
+     * @return a double at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      */
     public abstract double get(int index);
 
     /**
-     * Returns whether this buffer is based on a double array and is read/write.
-     * <p>
-     * If this buffer is readonly, then false is returned.
-     * </p>
-     * 
-     * @return Whether this buffer is based on a double array and is read/write.
+     * Indicates whether this buffer is based on a double array and is
+     * read/write.
+     *
+     * @return {@code true} if this buffer is based on a double array and
+     *         provides read/write access, {@code false} otherwise.
      */
     public final boolean hasArray() {
         return protectedHasArray();
     }
 
     /**
-     * Hash code is calculated from the remaining <code>double</code>s.
-     * <p>
-     * Position, limit, capacity and mark don't affect the hash code.
-     * </p>
-     * 
-     * @return The hash code calculated from the remaining <code>double</code>s.
+     * Calculates this buffer's hash code from the remaining chars. The
+     * position, limit, capacity and mark don't affect the hash code.
+     *
+     * @return the hash code calculated from the remaining chars.
      */
     @Override
     public int hashCode() {
@@ -368,113 +346,103 @@
     }
 
     /**
-     * Returns true if this buffer is direct.
-     * <p>
-     * A direct buffer will try its best to take advantage of native memory APIs
-     * and it may not stay in java heap, thus not affected by GC.
-     * </p>
+     * Indicates whether this buffer is direct. A direct buffer will try its
+     * best to take advantage of native memory APIs and it may not stay in the
+     * Java heap, so it is not affected by garbage collection.
      * <p>
-     * A double buffer is direct, if it is based on a byte buffer and the byte
+     * A double buffer is direct if it is based on a byte buffer and the byte
      * buffer is direct.
-     * </p>
      * 
-     * @return True if this buffer is direct.
+     * @return {@code true} if this buffer is direct, {@code false} otherwise.
      */
     public abstract boolean isDirect();
 
     /**
-     * Returns the byte order used by this buffer when converting
-     * <code>double</code>s from/to <code>byte</code>s.
+     * Returns the byte order used by this buffer when converting doubles
+     * from/to bytes.
      * <p>
-     * If this buffer is not based on a byte buffer, then always return the
-     * platform's native byte order.
-     * </p>
-     * 
-     * @return The byte order used by this buffer when converting
-     *         <code>double</code>s from/to <code>byte</code>s.
+     * If this buffer is not based on a byte buffer, then this always returns
+     * the platform's native byte order.
+     *
+     * @return the byte order used by this buffer when converting doubles
+     *         from/to bytes.
      */
     public abstract ByteOrder order();
 
     /**
-     * Child class implements this method to realize <code>array()</code>.
-     * 
-     * @return see <code>array()</code>
+     * Child class implements this method to realize {@code array()}.
+     *
+     * @see #array()
      */
     abstract double[] protectedArray();
 
     /**
-     * Child class implements this method to realize <code>arrayOffset()</code>.
-     * 
-     * @return see <code>arrayOffset()</code>
+     * Child class implements this method to realize {@code arrayOffset()}.
+     *
+     * @see #arrayOffset()
      */
     abstract int protectedArrayOffset();
 
     /**
-     * Child class implements this method to realize <code>hasArray()</code>.
-     * 
-     * @return see <code>hasArray()</code>
+     * Child class implements this method to realize {@code hasArray()}.
+     *
+     * @see #hasArray()
      */
     abstract boolean protectedHasArray();
 
     /**
-     * Writes the given double to the current position and increase the position
-     * by 1.
+     * Writes the given double to the current position and increases the
+     * position by 1.
      * 
      * @param d
-     *            The double to write
-     * @return This buffer
+     *            the double to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is equal or greater than limit
+     *                if position is equal or greater than limit.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public abstract DoubleBuffer put(double d);
 
     /**
-     * Writes <code>double</code>s in the given double array to the current
-     * position and increase the position by the number of <code>double</code>s
-     * written.
+     * Writes doubles from the given double array to the current position and
+     * increases the position by the number of doubles written.
      * <p>
      * Calling this method has the same effect as
-     * <code>put(src, 0, src.length)</code>.
-     * </p>
-     * 
+     * {@code put(src, 0, src.length)}.
+     *
      * @param src
-     *            The source double array
-     * @return This buffer
+     *            the source double array.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>remaining()</code> is less than
-     *                <code>src.length</code>
+     *                if {@code remaining()} is less than {@code src.length}.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public final DoubleBuffer put(double[] src) {
         return put(src, 0, src.length);
     }
 
     /**
-     * Writes <code>double</code>s in the given double array, starting from
-     * the specified offset, to the current position and increase the position
-     * by the number of <code>double</code>s written.
+     * Writes doubles from the given double array, starting from the specified
+     * offset, to the current position and increases the position by the number
+     * of doubles written.
      * 
      * @param src
-     *            The source double array
+     *            the source double array.
      * @param off
-     *            The offset of double array, must be no less than zero and no
-     *            greater than <code>src.length</code>
+     *            the offset of double array, must not be negative and not
+     *            greater than {@code src.length}.
      * @param len
-     *            The number of <code>double</code>s to write, must be no
-     *            less than zero and no greater than
-     *            <code>src.length - off</code>
-     * @return This buffer
+     *            the number of doubles to write, must be no less than zero and
+     *            not greater than {@code src.length - off}.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>remaining()</code> is less than
-     *                <code>len</code>
+     *                if {@code remaining()} is less than {@code len}.
      * @exception IndexOutOfBoundsException
-     *                If either <code>off</code> or <code>len</code> is
-     *                invalid
+     *                if either {@code off} or {@code len} is invalid.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public DoubleBuffer put(double[] src, int off, int len) {
         int length = src.length;
@@ -492,20 +460,20 @@
     }
 
     /**
-     * Writes all the remaining <code>double</code>s of the <code>src</code>
-     * double buffer to this buffer's current position, and increase both
-     * buffers' position by the number of <code>double</code>s copied.
+     * Writes all the remaining doubles of the {@code src} double buffer to this
+     * buffer's current position, and increases both buffers' position by the
+     * number of doubles copied.
      * 
      * @param src
-     *            The source double buffer
-     * @return This buffer
+     *            the source double buffer.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If <code>src.remaining()</code> is greater than this
-     *                buffer's <code>remaining()</code>
+     *                if {@code src.remaining()} is greater than this buffer's
+     *                {@code remaining()}.
      * @exception IllegalArgumentException
-     *                If <code>src</code> is this buffer
+     *                if {@code src} is this buffer.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public DoubleBuffer put(DoubleBuffer src) {
         if (src == this) {
@@ -525,40 +493,38 @@
      * not changed.
      * 
      * @param index
-     *            The index, must be no less than zero and less than the limit
+     *            the index, must not be negative and less than the limit.
      * @param d
-     *            The double to write
-     * @return This buffer
+     *            the double to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      * @exception ReadOnlyBufferException
-     *                If no changes may be made to the contents of this buffer
+     *                if no changes may be made to the contents of this buffer.
      */
     public abstract DoubleBuffer put(int index, double d);
 
     /**
-     * Returns a sliced buffer that shares content with this buffer.
+     * Returns a sliced buffer that shares its content with this buffer.
      * <p>
-     * The sliced buffer's capacity will be this buffer's
-     * <code>remaining()</code>, and its zero position will correspond to
-     * this buffer's current position. The new buffer's position will be 0,
-     * limit will be its capacity, and its mark is unset. The new buffer's
-     * readonly property and byte order are same as this buffer.
-     * </p>
+     * The sliced buffer's capacity will be this buffer's {@code remaining()},
+     * and its zero position will correspond to this buffer's current position.
+     * The new buffer's position will be 0, limit will be its capacity, and its
+     * mark is cleared. The new buffer's read-only property and byte order are
+     * the same as this buffer's.
      * <p>
-     * The new buffer shares content with this buffer, which means either
+     * The new buffer shares its content with this buffer, which means either
      * buffer's change of content will be visible to the other. The two buffer's
      * position, limit and mark are independent.
-     * </p>
-     * 
-     * @return A sliced buffer that shares content with this buffer.
+     *
+     * @return a sliced buffer that shares its content with this buffer.
      */
     public abstract DoubleBuffer slice();
 
     /**
-     * Returns a string represents the state of this double buffer.
+     * Returns a string representing the state of this double buffer.
      * 
-     * @return A string represents the state of this double buffer.
+     * @return A string representing the state of this double buffer.
      */
     @Override
     public String toString() {



Mime
View raw message