harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r768919 [1/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
Author: tellison
Date: Mon Apr 27 10:23:36 2009
New Revision: 768919

URL: http://svn.apache.org/viewvc?rev=768919&view=rev
Log:
Apply partial patch for HARMONY-6178 (Javadocs for java.nio.*)
Excluding patches that relate to LOGGING module for the moment.

Modified:
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/CharBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DirectByteBuffers.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/DoubleBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/FloatBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/IntBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/InvalidMarkException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongToByteBufferAdapter.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/MappedByteBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ReadOnlyBufferException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ShortBuffer.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AlreadyConnectedException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/AsynchronousCloseException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ByteChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/CancelledKeyException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Channels.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedByInterruptException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedChannelException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ClosedSelectorException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ConnectionPendingException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/DatagramChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLock.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/FileLockInterruptionException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/GatheringByteChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalBlockingModeException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/IllegalSelectorException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/InterruptibleChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NoConnectionPendingException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonReadableChannelException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NonWritableChannelException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetBoundException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/NotYetConnectedException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/OverlappingFileLockException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Pipe.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ReadableByteChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ScatteringByteChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectableChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SelectionKey.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/Selector.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/ServerSocketChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/SocketChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnresolvedAddressException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/UnsupportedAddressTypeException.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/WritableByteChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractInterruptibleChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectableChannel.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/AbstractSelectionKey.java
    harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/channels/spi/SelectorProvider.java

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/Buffer.java Mon Apr 27 10:23:36 2009
@@ -19,32 +19,30 @@
 /**
  * A buffer is a list of elements of a specific primitive type.
  * <p>
- * A buffer can be described by following properties:
+ * A buffer can be described by the following properties:
  * <ul>
- * <li>Capacity, is the number of elements a buffer can hold. Capacity is no
- * less than zero and never changes.</li>
- * <li>Position, is a cursor of this buffer. Elements are read or write at the
- * position if you do not specify an index explicitly. Position is no less than
- * zero and no greater than the limit.</li>
- * <li>Limit controls the scope of accessible elements. You can only read or
+ * <li>Capacity: the number of elements a buffer can hold. Capacity may not be
+ * negative and never changes.</li>
+ * <li>Position: a cursor of this buffer. Elements are read or written at the
+ * position if you do not specify an index explicitly. Position may not be
+ * negative and not greater than the limit.</li>
+ * <li>Limit: controls the scope of accessible elements. You can only read or
  * write elements from index zero to <code>limit - 1</code>. Accessing
- * elements out of the scope will cause exception. Limit is no less than zero
- * and no greater than capacity.</li>
- * <li>Mark, is used to remember the current position, so that you can reset
- * the position later. Mark is no less than zero and no greater than position.</li>
- * <li>A buffer can be readonly or read-write. Trying to modify the elements of
- * a readonly buffer will cause <code>ReadOnlyBufferException</code>, while
- * changing the position, limit and mark of a readonly buffer is OK.</li>
+ * elements out of the scope will cause an exception. Limit may not be negative
+ * and not greater than capacity.</li>
+ * <li>Mark: used to remember the current position, so that you can reset the
+ * position later. Mark may not be negative and no greater than position.</li>
+ * <li>A buffer can be read-only or read-write. Trying to modify the elements
+ * of a read-only buffer will cause a <code>ReadOnlyBufferException</code>,
+ * while changing the position, limit and mark of a read-only buffer is OK.</li>
  * <li>A buffer can be direct or indirect. 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.</li>
+ * take advantage of native memory APIs and it may not stay in the Java heap,
+ * thus it is not affected by garbage collection.</li>
  * </ul>
- * </p>
  * <p>
  * Buffers are not thread-safe. If concurrent access to a buffer instance is
  * required, then the callers are responsible to take care of the
  * synchronization issues.
- * </p>
  */
 public abstract class Buffer {
 
@@ -59,13 +57,13 @@
     final int capacity;
 
     /**
-     * <code>limit - 1</code> is the last element that can be read or write.
+     * <code>limit - 1</code> is the last element that can be read or written.
      * Limit must be no less than zero and no greater than <code>capacity</code>.
      */
     int limit;
 
     /**
-     * Mark is the position will be set when <code>reset()</code> is called.
+     * Mark is where position will be set when <code>reset()</code> is called.
      * Mark is not set by default. Mark is always no less than zero and no
      * greater than <code>position</code>.
      */
@@ -94,7 +92,7 @@
     /**
      * Returns the capacity of this buffer.
      * 
-     * @return The number of elements that are contained in this buffer.
+     * @return the number of elements that are contained in this buffer.
      */
     public final int capacity() {
         return capacity;
@@ -103,13 +101,12 @@
     /**
      * Clears this buffer.
      * <p>
-     * While the content of this buffer is not changed the following internal
-     * changes take place : the current position is reset back to the start of
+     * While the content of this buffer is not changed, the following internal
+     * changes take place: the current position is reset back to the start of
      * the buffer, the value of the buffer limit is made equal to the capacity
-     * and mark is unset.
-     * </p>
-     * 
-     * @return This buffer
+     * and mark is cleared.
+     *
+     * @return this buffer.
      */
     public final Buffer clear() {
         position = 0;
@@ -123,12 +120,10 @@
      * <p>
      * The limit is set to the current position, then the position is set to
      * zero, and the mark is cleared.
-     * </p>
      * <p>
      * The content of this buffer is not changed.
-     * </p>
-     * 
-     * @return This buffer
+     *
+     * @return this buffer.
      */
     public final Buffer flip() {
         limit = position;
@@ -138,28 +133,28 @@
     }
 
     /**
-     * Returns true if there are remaining element(s) in this buffer.
-     * <p>
-     * Or more precisely, returns <code>position &lt; limit</code>.
-     * </p>
+     * Indicates if there are elements remaining in this buffer, that is if
+     * {@code position < limit}.
      * 
-     * @return True if there are remaining element(s) in this buffer.
+     * @return {@code true} if there are elements remaining in this buffer,
+     *         {@code false} otherwise.
      */
     public final boolean hasRemaining() {
         return position < limit;
     }
 
     /**
-     * Returns whether this buffer is readonly or not.
+     * Indicates whether this buffer is read-only.
      * 
-     * @return Whether this buffer is readonly or not.
+     * @return {@code true} if this buffer is read-only, {@code false}
+     *         otherwise.
      */
     public abstract boolean isReadOnly();
 
     /**
      * Returns the limit of this buffer.
      * 
-     * @return The limit of this buffer.
+     * @return the limit of this buffer.
      */
     public final int limit() {
         return limit;
@@ -172,14 +167,13 @@
      * <code>newLimit</code> then, on returning from this call, it will have
      * been adjusted to be equivalent to <code>newLimit</code>. If the mark
      * is set and is greater than the new limit, then it is cleared.
-     * </p>
-     * 
+     *
      * @param newLimit
-     *            The new limit, must be no less than zero and no greater than
-     *            capacity
-     * @return This buffer
+     *            the new limit, must not be negative and not greater than
+     *            capacity.
+     * @return this buffer.
      * @exception IllegalArgumentException
-     *                If <code>newLimit</code> is invalid.
+     *                if <code>newLimit</code> is invalid.
      */
     public final Buffer limit(int newLimit) {
         if (newLimit < 0 || newLimit > capacity) {
@@ -197,10 +191,10 @@
     }
 
     /**
-     * Mark the current position, so that the position may return to this point
+     * Marks the current position, so that the position may return to this point
      * later by calling <code>reset()</code>.
      * 
-     * @return This buffer
+     * @return this buffer.
      */
     public final Buffer mark() {
         mark = position;
@@ -210,7 +204,7 @@
     /**
      * Returns the position of this buffer.
      * 
-     * @return The value of this buffer's current position.
+     * @return the value of this buffer's current position.
      */
     public final int position() {
         return position;
@@ -219,16 +213,15 @@
     /**
      * Sets the position of this buffer.
      * <p>
-     * If the mark is set and is greater than the new position, then it is
+     * If the mark is set and it is greater than the new position, then it is
      * cleared.
-     * </p>
-     * 
+     *
      * @param newPosition
-     *            The new position, must be no less than zero and no greater
-     *            than limit
-     * @return This buffer
+     *            the new position, must be not negative and not greater than
+     *            limit.
+     * @return this buffer.
      * @exception IllegalArgumentException
-     *                If <code>newPosition</code> is invalid
+     *                if <code>newPosition</code> is invalid.
      */
     public final Buffer position(int newPosition) {
         if (newPosition < 0 || newPosition > limit) {
@@ -243,23 +236,21 @@
     }
 
     /**
-     * Returns the number of remaining elements in this buffer.
-     * <p>
-     * Or more precisely, returns <code>limit - position</code>.
-     * </p>
+     * Returns the number of remaining elements in this buffer, that is
+     * {@code limit - position}.
      * 
-     * @return The number of remaining elements in this buffer.
+     * @return the number of remaining elements in this buffer.
      */
     public final int remaining() {
         return limit - position;
     }
 
     /**
-     * Reset the position of this buffer to the <code>mark</code>.
+     * Resets the position of this buffer to the <code>mark</code>.
      * 
-     * @return This buffer
+     * @return this buffer.
      * @exception InvalidMarkException
-     *                If the mark is not set
+     *                if the mark is not set.
      */
     public final Buffer reset() {
         if (mark == UNSET_MARK) {
@@ -272,13 +263,10 @@
     /**
      * Rewinds this buffer.
      * <p>
-     * The position is set to zero, and the mark is cleared.
-     * </p>
-     * <p>
-     * The content of this buffer is not changed.
-     * </p>
-     * 
-     * @return This buffer
+     * The position is set to zero, and the mark is cleared. The content of this
+     * buffer is not changed.
+     *
+     * @return this buffer.
      */
     public final Buffer rewind() {
         position = 0;

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferOverflowException.java Mon Apr 27 10:23:36 2009
@@ -17,9 +17,8 @@
 package java.nio;
 
 /**
- * A <code>BufferOverflowException</code> is thrown when you try to write
- * elements to a buffer, but there is not enough remaining space in the buffer.
- * 
+ * A <code>BufferOverflowException</code> is thrown when elements are written
+ * to a buffer but there is not enough remaining space in the buffer.
  */
 public class BufferOverflowException extends RuntimeException {
 

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/BufferUnderflowException.java Mon Apr 27 10:23:36 2009
@@ -17,10 +17,8 @@
 package java.nio;
 
 /**
- * A <code>BufferUnderflowException</code> is thrown when you try to read
- * elements from a buffer, but there is not enough remaining elements in the
- * buffer.
- * 
+ * A <code>BufferUnderflowException</code> is thrown when elements are read
+ * from a buffer but there are not enough remaining elements in the buffer.
  */
 public class BufferUnderflowException extends RuntimeException {
 

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteBuffer.java Mon Apr 27 10:23:36 2009
@@ -20,9 +20,9 @@
 import org.apache.harmony.luni.platform.Endianness;
 
 /**
- * A buffer of <code>byte</code>s.
+ * A buffer for bytes.
  * <p>
- * A byte buffer can be created in either of the following ways:
+ * A byte buffer can be created in either one of the following ways:
  * <ul>
  * <li>{@link #allocate(int) Allocate} a new byte array and create a buffer
  * based on it;</li>
@@ -31,20 +31,19 @@
  * <li>{@link #wrap(byte[]) Wrap} an existing byte array to create a new
  * buffer.</li>
  * </ul>
- * </p>
- * 
+ *
  */
 public abstract class ByteBuffer extends Buffer implements
         Comparable<ByteBuffer> {
 
     /**
-     * Creates a byte buffer based on a new allocated byte array.
+     * Creates a byte buffer based on a newly allocated byte array.
      * 
      * @param capacity
-     *            The capacity of the new buffer
-     * @return The created byte buffer
+     *            the capacity of the new buffer
+     * @return the created byte buffer.
      * @throws IllegalArgumentException
-     *             If <code>capacity</code> is less than zero
+     *             if {@code capacity < 0}.
      */
     public static ByteBuffer allocate(int capacity) {
         if (capacity < 0) {
@@ -54,13 +53,13 @@
     }
 
     /**
-     * Creates a direct byte buffer based on a new allocated memory block.
+     * Creates a direct byte buffer based on a newly allocated memory block.
      * 
      * @param capacity
-     *            The capacity of the new buffer
-     * @return The created byte buffer
+     *            the capacity of the new buffer
+     * @return the created byte buffer.
      * @throws IllegalArgumentException
-     *             If <code>capacity</code> is less than zero
+     *             if {@code capacity < 0}.
      */
     public static ByteBuffer allocateDirect(int capacity) {
         if (capacity < 0) {
@@ -73,36 +72,33 @@
      * Creates a new byte buffer by wrapping the given byte 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 byte array which the new buffer will be based on
-     * @return The created byte buffer
+     *            the byte array which the new buffer will be based on
+     * @return the created byte buffer.
      */
     public static ByteBuffer wrap(byte[] array) {
         return BufferFactory.newByteBuffer(array);
     }
 
     /**
-     * Creates new a byte buffer by wrapping the given byte array.
+     * Creates a new byte buffer by wrapping the given byte 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 byte array which the new buffer will be based on
+     *            the byte 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 byte buffer
+     *            the length, must not be negative and not greater than
+     *            {@code array.length - start}.
+     * @return the created byte 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 ByteBuffer wrap(byte[] array, int start, int len) {
         int length = array.length;
@@ -118,28 +114,28 @@
     }
 
     /**
-     * The byte order of this buffer, default is <code>BIG_ENDIAN</code>.
+     * The byte order of this buffer, default is {@code BIG_ENDIAN}.
      */
     Endianness order = Endianness.BIG_ENDIAN;
 
     /**
-     * Constructs a <code>ByteBuffer</code> with given capacity.
+     * Constructs a {@code ByteBuffer} with given capacity.
      * 
      * @param capacity
-     *            The capacity of the buffer
+     *            the capacity of the buffer.
      */
     ByteBuffer(int capacity) {
         super(capacity);
     }
 
     /**
-     * Returns the byte array which this buffer is based on, if there's one.
+     * Returns the byte array which this buffer is based on, if there is one.
      * 
-     * @return The byte array which this buffer is based on
+     * @return the byte array which this buffer is based on.
      * @exception ReadOnlyBufferException
-     *                If this buffer is based on a readonly array
+     *                if this buffer is based on a read-only array.
      * @exception UnsupportedOperationException
-     *                If this buffer is not based on an array
+     *                if this buffer is not based on an array.
      */
     public final byte[] array() {
         return protectedArray();
@@ -147,17 +143,16 @@
 
     /**
      * Returns the offset of the byte 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 byte array which this buffer is based on
+     * The offset is the index of the array which corresponds to the zero
+     * position of the buffer.
+     *
+     * @return the offset of the byte array which this buffer is based on.
      * @exception ReadOnlyBufferException
-     *                If this buffer is based on a readonly array
+     *                if this buffer is based on a read-only array.
      * @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();
@@ -169,16 +164,14 @@
      * <p>
      * The new buffer's position is zero, its limit and capacity is the number
      * of remaining bytes divided by two, and its mark is not set. The new
-     * buffer's readonly property and byte order are same as this buffer. The
-     * new buffer is direct, if this byte buffer is direct.
-     * </p>
+     * buffer's read-only property and byte order are the same as this buffer's.
+     * The new buffer is direct if this byte buffer is direct.
      * <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 char buffer which is based on the content of this byte buffer.
+     *
+     * @return a char buffer which is based on the content of this byte buffer.
      */
     public abstract CharBuffer asCharBuffer();
 
@@ -187,17 +180,15 @@
      * byte buffer.
      * <p>
      * The new buffer's position is zero, its limit and capacity is the number
-     * of remaining bytes divided by two, and its mark is not set. The new
-     * buffer's readonly property and byte order are same as this buffer. The
-     * new buffer is direct, if this byte buffer is direct.
-     * </p>
+     * of remaining bytes divided by eight, and its mark is not set. The new
+     * buffer's read-only property and byte order are the same as this buffer's.
+     * The new buffer is direct if this byte buffer is direct.
      * <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 double buffer which is based on the content of this byte
+     *
+     * @return a double buffer which is based on the content of this byte
      *         buffer.
      */
     public abstract DoubleBuffer asDoubleBuffer();
@@ -207,17 +198,15 @@
      * byte buffer.
      * <p>
      * The new buffer's position is zero, its limit and capacity is the number
-     * of remaining bytes divided by two, and its mark is not set. The new
-     * buffer's readonly property and byte order are same as this buffer. The
-     * new buffer is direct, if this byte buffer is direct.
-     * </p>
+     * of remaining bytes divided by four, and its mark is not set. The new
+     * buffer's read-only property and byte order are the same as this buffer's.
+     * The new buffer is direct if this byte buffer is direct.
      * <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 float buffer which is based on the content of this byte buffer.
+     *
+     * @return a float buffer which is based on the content of this byte buffer.
      */
     public abstract FloatBuffer asFloatBuffer();
 
@@ -226,17 +215,15 @@
      * buffer.
      * <p>
      * The new buffer's position is zero, its limit and capacity is the number
-     * of remaining bytes divided by two, and its mark is not set. The new
-     * buffer's readonly property and byte order are same as this buffer. The
-     * new buffer is direct, if this byte buffer is direct.
-     * </p>
+     * of remaining bytes divided by four, and its mark is not set. The new
+     * buffer's read-only property and byte order are the same as this buffer's.
+     * The new buffer is direct if this byte buffer is direct.
      * <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 int buffer which is based on the content of this byte buffer.
+     *
+     * @return a int buffer which is based on the content of this byte buffer.
      */
     public abstract IntBuffer asIntBuffer();
 
@@ -245,34 +232,30 @@
      * byte buffer.
      * <p>
      * The new buffer's position is zero, its limit and capacity is the number
-     * of remaining bytes divided by two, and its mark is not set. The new
-     * buffer's readonly property and byte order are same as this buffer. The
-     * new buffer is direct, if this byte buffer is direct.
-     * </p>
+     * of remaining bytes divided by eight, and its mark is not set. The new
+     * buffer's read-only property and byte order are the same as this buffer's.
+     * The new buffer is direct if this byte buffer is direct.
      * <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 long buffer which is based on the content of this byte buffer.
+     *
+     * @return a long buffer which is based on the content of this byte buffer.
      */
     public abstract LongBuffer asLongBuffer();
 
     /**
-     * Returns a readonly buffer that shares content with this buffer.
-     * <p>
-     * The returned buffer is guaranteed to be a new instance, even if 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.
+     * <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 ByteBuffer asReadOnlyBuffer();
 
@@ -282,45 +265,42 @@
      * <p>
      * The new buffer's position is zero, its limit and capacity is the number
      * of remaining bytes divided by two, and its mark is not set. The new
-     * buffer's readonly property and byte order are same as this buffer. The
-     * new buffer is direct, if this byte buffer is direct.
-     * </p>
+     * buffer's read-only property and byte order are the same as this buffer's.
+     * The new buffer is direct if this byte buffer is direct.
      * <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 short buffer which is based on the content of this byte buffer.
+     *
+     * @return a short buffer which is based on the content of this byte buffer.
      */
     public abstract ShortBuffer asShortBuffer();
 
     /**
      * Compacts this byte buffer.
      * <p>
-     * The remaining <code>byte</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
+     * The remaining bytes 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.
-     * </p>
-     * 
-     * @return This buffer
+     *
+     * @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 ByteBuffer compact();
 
     /**
-     * Compare the remaining <code>byte</code>s of this buffer to another
-     * byte buffer's remaining <code>byte</code>s.
+     * Compares the remaining bytes of this buffer to another byte buffer's
+     * remaining bytes.
      * 
      * @param otherBuffer
-     *            Another byte 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 byte 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 byte buffer
+     *                if {@code other} is not a byte buffer.
      */
     public int compareTo(ByteBuffer otherBuffer) {
         int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -342,36 +322,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 ByteBuffer duplicate();
 
     /**
-     * Tests whether this byte buffer equals to another object.
-     * <p>
-     * If <code>other</code> is not a byte buffer, then false is returned.
-     * </p>
+     * Checks whether this byte buffer is equal to another object.
      * <p>
-     * Two byte buffers are equals if, and only if, their remaining
-     * <code>byte</code>s are exactly the same. Position, limit, capacity and
-     * mark are not considered.
-     * </p>
-     * 
+     * If {@code other} is not a byte buffer then {@code false} is returned. Two
+     * byte buffers are equal if and only if their remaining bytes are exactly
+     * the same. Position, limit, capacity and mark are not considered.
+     *
      * @param other
-     *            the object to compare against
-     * @return Whether this byte buffer equals to another object.
+     *            the object to compare with this byte buffer.
+     * @return {@code true} if this byte buffer is equal to {@code other},
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object other) {
@@ -395,54 +370,49 @@
     }
 
     /**
-     * Returns the byte at the current position and increase the position by 1.
+     * Returns the byte at the current position and increases the position by 1.
      * 
-     * @return The byte at the current position.
+     * @return the byte 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 byte get();
 
     /**
-     * Reads <code>byte</code>s from the current position into the specified
-     * byte array and increase the position by the number of <code>byte</code>s
-     * read.
+     * Reads bytes from the current position into the specified byte array and
+     * increases the position by the number of bytes 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 byte array
-     * @return This buffer
+     *            the destination byte 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 ByteBuffer get(byte[] dest) {
         return get(dest, 0, dest.length);
     }
 
     /**
-     * Reads <code>byte</code>s from the current position into the specified
-     * byte array, starting from the specified offset, and increase the position
-     * by the number of <code>byte</code>s read.
+     * Reads bytes from the current position into the specified byte array,
+     * starting at the specified offset, and increases the position by the
+     * number of bytes read.
      * 
      * @param dest
-     *            The target byte array
+     *            the target byte array.
      * @param off
-     *            The offset of the byte array, must be no less than zero and no
-     *            greater than <code>dest.length</code>
+     *            the offset of the byte array, must not be negative and
+     *            not greater than {@code dest.length}.
      * @param len
-     *            The number of <code>byte</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 bytes to read, must not be negative 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 ByteBuffer get(byte[] dest, int off, int len) {
         int length = dest.length;
@@ -460,222 +430,202 @@
     }
 
     /**
-     * Returns a byte at the specified index, and the position is not changed.
+     * Returns the byte at the specified index and does not change the position.
      * 
      * @param index
-     *            The index, must be no less than zero and less than limit
-     * @return A byte at the specified index.
+     *            the index, must not be negative and less than limit.
+     * @return the byte at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      */
     public abstract byte get(int index);
 
     /**
-     * Returns the char at the current position and increase the position by 2.
+     * Returns the char at the current position and increases the position by 2.
      * <p>
-     * The 2 bytes start from the current position are composed into a char
-     * according to current byte order and returned. The position increases by
-     * 2.
-     * </p>
-     * 
-     * @return The char at the current position.
+     * The 2 bytes starting at the current position are composed into a char
+     * according to the current byte order and returned.
+     *
+     * @return the char at the current position.
      * @exception BufferUnderflowException
-     *                If the position is greater than <code>limit - 2</code>
+     *                if the position is greater than {@code limit - 2}.
      */
     public abstract char getChar();
 
     /**
      * Returns the char at the specified index.
      * <p>
-     * The 2 bytes start from the specified index are composed into a char
-     * according to current byte order and returned. The position is not
+     * The 2 bytes starting from the specified index are composed into a char
+     * according to the current byte order and returned. The position is not
      * changed.
-     * </p>
      * 
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 2</code>
-     * @return The char at the specified index.
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 2}.
+     * @return the char at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code index} is invalid.
      */
     public abstract char getChar(int index);
 
     /**
-     * Returns the double at the current position and increase the position by
+     * Returns the double at the current position and increases the position by
      * 8.
      * <p>
-     * The 8 bytes start from the current position are composed into a double
-     * according to current byte order and returned. The position increases by
-     * 8.
-     * </p>
-     * 
-     * @return The double at the current position.
+     * The 8 bytes starting from the current position are composed into a double
+     * according to the current byte order and returned.
+     *
+     * @return the double at the current position.
      * @exception BufferUnderflowException
-     *                If the position is greater than <code>limit - 8</code>
+     *                if the position is greater than {@code limit - 8}.
      */
     public abstract double getDouble();
 
     /**
      * Returns the double at the specified index.
      * <p>
-     * The 8 bytes start from the specified index are composed into a double
-     * according to current byte order and returned. The position is not
+     * The 8 bytes starting at the specified index are composed into a double
+     * according to the current byte order and returned. The position is not
      * changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 8</code>
-     * @return The double at the specified index.
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 8}.
+     * @return the double at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code index} is invalid.
      */
     public abstract double getDouble(int index);
 
     /**
-     * Returns the float at the current position and increase the position by 4.
-     * <p>
-     * The 4 bytes start from the current position are composed into a float
-     * according to current byte order and returned. The position increases by
+     * Returns the float at the current position and increases the position by
      * 4.
-     * </p>
-     * 
-     * @return The float at the current position.
+     * <p>
+     * The 4 bytes starting at the current position are composed into a float
+     * according to the current byte order and returned.
+     *
+     * @return the float at the current position.
      * @exception BufferUnderflowException
-     *                If the position is greater than <code>limit - 4</code>
+     *                if the position is greater than {@code limit - 4}.
      */
     public abstract float getFloat();
 
     /**
      * Returns the float at the specified index.
      * <p>
-     * The 4 bytes start from the specified index are composed into a float
-     * according to current byte order and returned. The position is not
+     * The 4 bytes starting at the specified index are composed into a float
+     * according to the current byte order and returned. The position is not
      * changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 4</code>
-     * @return The float at the specified index.
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 4}.
+     * @return the float at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code index} is invalid.
      */
     public abstract float getFloat(int index);
 
     /**
-     * Returns the int at the current position and increase the position by 4.
+     * Returns the int at the current position and increases the position by 4.
      * <p>
-     * The 4 bytes start from the current position are composed into a int
-     * according to current byte order and returned. The position increases by
-     * 4.
-     * </p>
-     * 
-     * @return The int at the current position.
+     * The 4 bytes starting at the current position are composed into a int
+     * according to the current byte order and returned.
+     *
+     * @return the int at the current position.
      * @exception BufferUnderflowException
-     *                If the position is greater than <code>limit - 4</code>
+     *                if the position is greater than {@code limit - 4}.
      */
     public abstract int getInt();
 
     /**
      * Returns the int at the specified index.
      * <p>
-     * The 4 bytes start from the specified index are composed into a int
-     * according to current byte order and returned. The position is not
+     * The 4 bytes starting at the specified index are composed into a int
+     * according to the current byte order and returned. The position is not
      * changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 4</code>
-     * @return The int at the specified index.
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 4}.
+     * @return the int at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code index} is invalid.
      */
     public abstract int getInt(int index);
 
     /**
-     * Returns the long at the current position and increase the position by 8.
+     * Returns the long at the current position and increases the position by 8.
      * <p>
-     * The 8 bytes start from the current position are composed into a long
-     * according to current byte order and returned. The position increases by
-     * 8.
-     * </p>
-     * 
-     * @return The long at the current position.
+     * The 8 bytes starting at the current position are composed into a long
+     * according to the current byte order and returned.
+     *
+     * @return the long at the current position.
      * @exception BufferUnderflowException
-     *                If the position is greater than <code>limit - 8</code>
+     *                if the position is greater than {@code limit - 8}.
      */
     public abstract long getLong();
 
     /**
      * Returns the long at the specified index.
      * <p>
-     * The 8 bytes start from the specified index are composed into a long
-     * according to current byte order and returned. The position is not
+     * The 8 bytes starting at the specified index are composed into a long
+     * according to the current byte order and returned. The position is not
      * changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 8</code>
-     * @return The long at the specified index.
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 8}.
+     * @return the long at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code index} is invalid.
      */
     public abstract long getLong(int index);
 
     /**
-     * Returns the short at the current position and increase the position by 2.
+     * Returns the short at the current position and increases the position by 2.
      * <p>
-     * The 2 bytes start from the current position are composed into a short
-     * according to current byte order and returned. The position increases by
-     * 2.
-     * </p>
-     * 
-     * @return The short at the current position.
+     * The 2 bytes starting at the current position are composed into a short
+     * according to the current byte order and returned.
+     *
+     * @return the short at the current position.
      * @exception BufferUnderflowException
-     *                If the position is greater than <code>limit - 2</code>
+     *                if the position is greater than {@code limit - 2}.
      */
     public abstract short getShort();
 
     /**
      * Returns the short at the specified index.
      * <p>
-     * The 2 bytes start from the specified index are composed into a short
-     * according to current byte order and returned. The position is not
+     * The 2 bytes starting at the specified index are composed into a short
+     * according to the current byte order and returned. The position is not
      * changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 2</code>
-     * @return The short at the specified index.
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 2}.
+     * @return the short at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code index} is invalid.
      */
     public abstract short getShort(int index);
 
     /**
-     * Returns whether this buffer is based on a byte array and is read/write.
-     * <p>
-     * If this buffer is readonly, then false is returned.
-     * </p>
+     * Indicates whether this buffer is based on a byte array and provides
+     * read/write access.
      * 
-     * @return Whether this buffer is based on a byte 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>byte</code>s.
-     * <p>
-     * Position, limit, capacity and mark don't affect the hash code.
-     * </p>
-     * 
-     * @return The hash code calculated from the remaining <code>byte</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 bytes.
      */
     @Override
     public int hashCode() {
@@ -688,25 +638,21 @@
     }
 
     /**
-     * Returns true if this buffer is direct.
-     * <p>
-     * A byte 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.
+     * Indicates whether 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>byte</code>s from/to other primitive types.
+     * Returns the byte order used by this buffer when converting bytes from/to
+     * other primitive types.
      * <p>
-     * The default byte order of byte buffer is always BIG_ENDIAN.
-     * </p>
-     * 
-     * @return The byte order used by this buffer when converting
-     *         <code>byte</code>s from/to other primitive types.
+     * The default byte order of byte buffer is always
+     * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
+     *
+     * @return the byte order used by this buffer when converting bytes from/to
+     *         other primitive types.
      */
     public final ByteOrder order() {
         return order == Endianness.BIG_ENDIAN ? ByteOrder.BIG_ENDIAN
@@ -717,9 +663,9 @@
      * Sets the byte order of this buffer.
      * 
      * @param byteOrder
-     *            The byte order to set. If <code>null</code> then the order
+     *            the byte order to set. If {@code null} then the order
      *            will be {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}.
-     * @return This buffer
+     * @return this buffer.
      * @see ByteOrder
      */
     public final ByteBuffer order(ByteOrder byteOrder) {
@@ -733,88 +679,83 @@
     }
 
     /**
-     * Child class implements this method to realize <code>array()</code>.
+     * Child class implements this method to realize {@code array()}.
      * 
-     * @return see <code>array()</code>
+     * @see #array()
      */
     abstract byte[] protectedArray();
 
     /**
-     * Child class implements this method to realize <code>arrayOffset()</code>.
+     * Child class implements this method to realize {@code arrayOffset()}.
      * 
-     * @return see <code>arrayOffset()</code>
+     * @see #arrayOffset()
      */
     abstract int protectedArrayOffset();
 
     /**
-     * Child class implements this method to realize <code>hasArray()</code>.
+     * Child class implements this method to realize {@code hasArray()}.
      * 
-     * @return see <code>hasArray()</code>
+     * @see #hasArray()
      */
     abstract boolean protectedHasArray();
 
     /**
-     * Writes the given byte to the current position and increase the position
+     * Writes the given byte to the current position and increases the position
      * by 1.
      * 
      * @param b
-     *            The byte to write
-     * @return This buffer
+     *            the byte 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 ByteBuffer put(byte b);
 
     /**
-     * Writes <code>byte</code>s in the given byte array to the current
-     * position and increase the position by the number of <code>byte</code>s
-     * written.
+     * Writes bytes in the given byte array to the current position and
+     * increases the position by the number of bytes 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 byte array
-     * @return This buffer
+     *            the source byte 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 ByteBuffer put(byte[] src) {
         return put(src, 0, src.length);
     }
 
     /**
-     * Writes <code>byte</code>s in the given byte array, starting from the
-     * specified offset, to the current position and increase the position by
-     * the number of <code>byte</code>s written.
+     * Writes bytes in the given byte array, starting from the specified offset,
+     * to the current position and increases the position by the number of bytes
+     * written.
      * 
      * @param src
-     *            The source byte array
+     *            the source byte array.
      * @param off
-     *            The offset of byte array, must be no less than zero and no
-     *            greater than <code>src.length</code>
+     *            the offset of byte array, must not be negative and not greater
+     *            than {@code src.length}.
      * @param len
-     *            The number of <code>byte</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 bytes to write, must not be negative 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 ByteBuffer put(byte[] src, int off, int len) {
         int length = src.length;
-        if ((off < 0) || (len < 0) || ((long) off + (long) len > length)) {
+        if ((off < 0 ) || (len < 0) || ((long)off + (long)len > length)) {
             throw new IndexOutOfBoundsException();
         }
 
@@ -828,20 +769,20 @@
     }
 
     /**
-     * Writes all the remaining <code>byte</code>s of the <code>src</code>
-     * byte buffer to this buffer's current position, and increase both buffers'
-     * position by the number of <code>byte</code>s copied.
+     * Writes all the remaining bytes of the {@code src} byte buffer to this
+     * buffer's current position, and increases both buffers' position by the
+     * number of bytes copied.
      * 
      * @param src
-     *            The source byte buffer
-     * @return This buffer
+     *            the source byte 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 ByteBuffer put(ByteBuffer src) {
         if (src == this) {
@@ -857,266 +798,252 @@
     }
 
     /**
-     * Write a byte to the specified index of this buffer and the position is
-     * not changed.
+     * Write a byte to the specified index of this buffer without changing the
+     * position.
      * 
      * @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 b
-     *            The byte to write
-     * @return This buffer
+     *            the byte to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code 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 ByteBuffer put(int index, byte b);
 
     /**
-     * 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 2.
      * <p>
      * The char is converted to bytes using the current byte order.
-     * </p>
-     * 
+     *
      * @param value
-     *            The char to write
-     * @return This buffer
+     *            the char to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is greater than <code>limit - 2</code>
+     *                if position is greater than {@code limit - 2}.
      * @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 ByteBuffer putChar(char value);
 
     /**
-     * Write a char to the specified index of this buffer.
+     * Writes the given char to the specified index of this buffer.
      * <p>
      * The char is converted to bytes using the current byte order. The position
      * is not changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 2</code>
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 2}.
      * @param value
-     *            The char to write
-     * @return This buffer
+     *            the char to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code 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 ByteBuffer putChar(int index, char value);
 
     /**
-     * Writes the given double to the current position and increase the position
+     * Writes the given double to the current position and increases the position
      * by 8.
      * <p>
      * The double is converted to bytes using the current byte order.
-     * </p>
-     * 
+     *
      * @param value
-     *            The double to write
-     * @return This buffer
+     *            the double to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is greater than <code>limit - 8</code>
+     *                if position is greater than {@code limit - 8}.
      * @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 ByteBuffer putDouble(double value);
 
     /**
-     * Write a double to the specified index of this buffer.
+     * Writes the given double to the specified index of this buffer.
      * <p>
      * The double is converted to bytes using the current byte order. The
      * position is not changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 8</code>
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 8}.
      * @param value
-     *            The double to write
-     * @return This buffer
+     *            the double to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code 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 ByteBuffer putDouble(int index, double value);
 
     /**
-     * Writes the given float to the current position and increase the position
+     * Writes the given float to the current position and increases the position
      * by 4.
      * <p>
      * The float is converted to bytes using the current byte order.
-     * </p>
-     * 
+     *
      * @param value
-     *            The float to write
-     * @return This buffer
+     *            the float to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is greater than <code>limit - 4</code>
+     *                if position is greater than {@code limit - 4}.
      * @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 ByteBuffer putFloat(float value);
 
     /**
-     * Write a float to the specified index of this buffer.
+     * Writes the given float to the specified index of this buffer.
      * <p>
      * The float is converted to bytes using the current byte order. The
      * position is not changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 4</code>
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 4}.
      * @param value
-     *            The float to write
-     * @return This buffer
+     *            the float to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code 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 ByteBuffer putFloat(int index, float value);
 
     /**
-     * Writes the given int to the current position and increase the position by
+     * Writes the given int to the current position and increases the position by
      * 4.
      * <p>
      * The int is converted to bytes using the current byte order.
-     * </p>
-     * 
+     *
      * @param value
-     *            The int to write
-     * @return This buffer
+     *            the int to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is greater than <code>limit - 4</code>
+     *                if position is greater than {@code limit - 4}.
      * @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 ByteBuffer putInt(int value);
 
     /**
-     * Write a int to the specified index of this buffer.
+     * Writes the given int to the specified index of this buffer.
      * <p>
      * The int is converted to bytes using the current byte order. The position
      * is not changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 4</code>
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 4}.
      * @param value
-     *            The int to write
-     * @return This buffer
+     *            the int to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code 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 ByteBuffer putInt(int index, int value);
 
     /**
-     * Writes the given long to the current position and increase the position
+     * Writes the given long to the current position and increases the position
      * by 8.
      * <p>
      * The long is converted to bytes using the current byte order.
-     * </p>
-     * 
+     *
      * @param value
-     *            The long to write
-     * @return This buffer
+     *            the long to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is greater than <code>limit - 8</code>
+     *                if position is greater than {@code limit - 8}.
      * @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 ByteBuffer putLong(long value);
 
     /**
-     * Write a long to the specified index of this buffer.
+     * Writes the given long to the specified index of this buffer.
      * <p>
      * The long is converted to bytes using the current byte order. The position
      * is not changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 8</code>
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 8}.
      * @param value
-     *            The long to write
-     * @return This buffer
+     *            the long to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code 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 ByteBuffer putLong(int index, long value);
 
     /**
-     * Writes the given short to the current position and increase the position
+     * Writes the given short to the current position and increases the position
      * by 2.
      * <p>
      * The short is converted to bytes using the current byte order.
-     * </p>
-     * 
+     *
      * @param value
-     *            The short to write
-     * @return This buffer
+     *            the short to write.
+     * @return this buffer.
      * @exception BufferOverflowException
-     *                If position is greater than <code>limit - 2</code>
+     *                if position is greater than {@code limit - 2}.
      * @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 ByteBuffer putShort(short value);
 
     /**
-     * Write a short to the specified index of this buffer.
+     * Writes the given short to the specified index of this buffer.
      * <p>
      * The short is converted to bytes using the current byte order. The
      * position is not changed.
-     * </p>
-     * 
+     *
      * @param index
-     *            The index, must be no less than zero and equal or less than
-     *            <code>limit - 2</code>
+     *            the index, must not be negative and equal or less than
+     *            {@code limit - 2}.
      * @param value
-     *            The short to write
-     * @return This buffer
+     *            the short to write.
+     * @return this buffer.
      * @exception IndexOutOfBoundsException
-     *                If <code>index</code> is invalid
+     *                if {@code 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 ByteBuffer putShort(int index, short value);
 
     /**
-     * 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
+     * {@code remaining()}, and it's 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>
+     * 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 ByteBuffer slice();
 
     /**
-     * Returns a string represents the state of this byte buffer.
+     * Returns a string representing the state of this byte buffer.
      * 
-     * @return A string represents the state of this byte buffer.
+     * @return a string representing the state of this byte buffer.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ByteOrder.java Mon Apr 27 10:23:36 2009
@@ -19,8 +19,7 @@
 import org.apache.harmony.luni.platform.Platform;
 
 /**
- * Holds byte order constants.
- * 
+ * Defines byte order constants.
  */
 public final class ByteOrder {
 
@@ -45,10 +44,10 @@
     }
 
     /**
-     * Answers the current platform byte order.
+     * Returns the current platform byte order.
      * 
-     * @return the byte order object, which is either identical to LITTLE_ENDIAN
-     *         or BIG_ENDIAN.
+     * @return the byte order object, which is either LITTLE_ENDIAN or
+     *         BIG_ENDIAN.
      */
     public static ByteOrder nativeOrder() {
         return NATIVE_ORDER;
@@ -61,10 +60,12 @@
         this.name = name;
     }
 
-    /*
-     * (non-Javadoc)
+    /**
+     * Returns a string that describes this object.
      * 
-     * @see java.lang.Object#toString()
+     * @return "BIG_ENDIAN" for {@link #BIG_ENDIAN ByteOrder.BIG_ENDIAN}
+     *         objects, "LITTLE_ENDIAN" for
+     *         {@link #LITTLE_ENDIAN ByteOrder.LITTLE_ENDIAN} objects.
      */
     @Override
     public String toString() {



Mime
View raw message