harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From telli...@apache.org
Subject svn commit: r768919 [3/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/FloatBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/FloatBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/FloatBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/FloatBuffer.java Mon Apr 27 10:23:36 2009
@@ -18,7 +18,7 @@
 package java.nio;
 
 /**
- * A buffer of <code>float</code>s.
+ * A buffer of floats.
  * <p>
  * A float buffer can be created in either of the following ways:
  * <ul>
@@ -29,19 +29,18 @@
  * <li>Use {@link java.nio.ByteBuffer#asFloatBuffer() ByteBuffer.asFloatBuffer}
  * to create a float buffer based on a byte buffer.</li>
  * </ul>
- * </p>
  */
 public abstract class FloatBuffer extends Buffer implements
         Comparable<FloatBuffer> {
 
     /**
-     * Creates a float buffer based on a new allocated float array.
+     * Creates a float buffer based on a newly allocated float array.
      * 
      * @param capacity
-     *            The capacity of the new buffer
-     * @return The created float buffer
+     *            the capacity of the new buffer.
+     * @return the created float buffer.
      * @throws IllegalArgumentException
-     *             If <code>capacity</code> is less than zero
+     *             if {@code capacity} is less than zero.
      */
     public static FloatBuffer allocate(int capacity) {
         if (capacity < 0) {
@@ -54,36 +53,35 @@
      * Creates a new float buffer by wrapping the given float 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 float array which the new buffer will be based on
-     * @return The created float buffer
+     *            the float array which the new buffer will be based on.
+     * @return the created float buffer.
      */
     public static FloatBuffer wrap(float[] array) {
         return wrap(array, 0, array.length);
     }
 
     /**
-     * Creates new a float buffer by wrapping the given float array.
+     * Creates a new float buffer by wrapping the given float 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 float array which the new buffer will be based on
+     *            the float 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 float buffer
+     *            the length, must not be negative and not greater than
+     *            {@code array.length - start}.
+     * @return the created float buffer.
      * @exception IndexOutOfBoundsException
-     *                If either <code>start</code> or <code>len</code> is
-     *                invalid
+     *                if either {@code start} or {@code len} is invalid.
+     * @exception NullPointerException
+     *                if {@code array} is null.
      */
     public static FloatBuffer wrap(float[] array, int start, int len) {
         if (array == null) {
@@ -101,23 +99,22 @@
     }
 
     /**
-     * Constructs a <code>FloatBuffer</code> with given capacity.
-     * 
-     * @param capacity
-     *            The capacity of the buffer
+     * Constructs a {@code FloatBuffer} with given capacity.
+     *
+     * @param capacity  The capacity of the buffer
      */
     FloatBuffer(int capacity) {
         super(capacity);
     }
 
     /**
-     * Returns the float array which this buffer is based on, if there's one.
+     * Returns the float array which this buffer is based on, if there is one.
      * 
-     * @return The float array which this buffer is based on
+     * @return the float 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 float[] array() {
         return protectedArray();
@@ -125,65 +122,60 @@
 
     /**
      * Returns the offset of the float 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 float array which this buffer is based on
+     * The offset is the index of the array and corresponds to the zero position
+     * of the buffer.
+     *
+     * @return the offset of the float 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.
+     * <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 FloatBuffer asReadOnlyBuffer();
 
     /**
      * Compacts this float buffer.
      * <p>
-     * The remaining <code>float</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 floats 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 FloatBuffer compact();
 
     /**
-     * Compare the remaining <code>float</code>s of this buffer to another
-     * float buffer's remaining <code>float</code>s.
+     * Compare the remaining floats of this buffer to another float buffer's
+     * remaining floats.
      * 
      * @param otherBuffer
-     *            Another float 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 float 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 float buffer
+     *                if {@code otherBuffer} is not a float buffer.
      */
     public int compareTo(FloatBuffer otherBuffer) {
         int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -207,36 +199,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
+     * as this buffer. The duplicated buffer's read-only property and byte order
      * are same as this buffer too.
-     * </p>
      * <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 FloatBuffer duplicate();
 
     /**
-     * Tests whether this float buffer equals to another object.
-     * <p>
-     * If <code>other</code> is not a float buffer, then false is returned.
-     * </p>
+     * Checks whether this float buffer is equal to another object.
      * <p>
-     * Two float buffers are equals if, and only if, their remaining
-     * <code>float</code>s are exactly the same. Position, limit, capacity
-     * and mark are not considered.
-     * </p>
-     * 
+     * If {@code other} is not a float buffer then {@code false} is returned.
+     * Two float buffers are equal if and only if their remaining floats are
+     * exactly the same. Position, limit, capacity and mark are not considered.
+     *
      * @param other
-     *            the object to be compared against
-     * @return Whether this float buffer equals to another object.
+     *            the object to compare with this float buffer.
+     * @return {@code true} if this float buffer is equal to {@code other},
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object other) {
@@ -260,54 +247,50 @@
     }
 
     /**
-     * Returns the float at the current position and increase the position by 1.
+     * Returns the float at the current position and increases the position by
+     * 1.
      * 
-     * @return The float at the current position.
+     * @return the float 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 float get();
 
     /**
-     * Reads <code>float</code>s from the current position into the specified
-     * float array and increase the position by the number of <code>float</code>s
-     * read.
+     * Reads floats from the current position into the specified float array and
+     * increases the position by the number of floats 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 float array
-     * @return This buffer
+     *            the destination float 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 FloatBuffer get(float[] dest) {
         return get(dest, 0, dest.length);
     }
 
     /**
-     * Reads <code>float</code>s from the current position into the specified
-     * float array, starting from the specified offset, and increase the
-     * position by the number of <code>float</code>s read.
+     * Reads floats from the current position into the specified float array,
+     * starting from the specified offset, and increases the position by the
+     * number of floats read.
      * 
      * @param dest
-     *            The target float array
+     *            the target float array.
      * @param off
-     *            The offset of the float array, must be no less than zero and
-     *            no greater than <code>dest.length</code>
+     *            the offset of the float array, must not be negative and no
+     *            greater than {@code dest.length}.
      * @param len
-     *            The number of <code>float</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 floats 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 FloatBuffer get(float[] dest, int off, int len) {
         int length = dest.length;
@@ -325,35 +308,32 @@
     }
 
     /**
-     * Returns a float at the specified index, and the position is not changed.
+     * Returns a float 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 float at the specified index.
+     *            the index, must not be negative and less than limit.
+     * @return a float at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      */
     public abstract float get(int index);
 
     /**
-     * Returns whether this buffer is based on a float array and is read/write.
-     * <p>
-     * If this buffer is readonly, then false is returned.
-     * </p>
-     * 
-     * @return Whether this buffer is based on a float array and is read/write.
+     * Indicates whether this buffer is based on a float array and is
+     * read/write.
+     *
+     * @return {@code true} if this buffer is based on a float array and
+     *         provides read/write access, {@code false} otherwise.
      */
     public final boolean hasArray() {
         return protectedHasArray();
     }
 
     /**
-     * Hash code is calculated from the remaining <code>float</code>s.
-     * <p>
-     * Position, limit, capacity and mark don't affect the hash code.
-     * </p>
-     * 
-     * @return The hash code calculated from the remaining <code>float</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 floats.
      */
     @Override
     public int hashCode() {
@@ -366,116 +346,107 @@
     }
 
     /**
-     * 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 float buffer is direct, if it is based on a byte buffer and the byte
+     * A float 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>float</code>s from/to <code>byte</code>s.
+     * Returns the byte order used by this buffer when converting floats 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>float</code>s from/to <code>byte</code>s.
+     *
+     * @return the byte order used by this buffer when converting floats 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()}.
+     *
+     * @return see {@code array()}
      */
     abstract float[] 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()}.
+     *
+     * @return see {@code 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()}.
+     *
+     * @return see {@code hasArray()}
      */
     abstract boolean protectedHasArray();
 
     /**
-     * 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 1.
      * 
      * @param f
-     *            The float to write
-     * @return This buffer
+     *            the float 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 FloatBuffer put(float f);
 
     /**
-     * Writes <code>float</code>s in the given float array to the current
-     * position and increase the position by the number of <code>float</code>s
-     * written.
+     * Writes floats from the given float array to the current position and
+     * increases the position by the number of floats 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 float array
-     * @return This buffer
+     *            the source float 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 FloatBuffer put(float[] src) {
         return put(src, 0, src.length);
     }
 
     /**
-     * Writes <code>float</code>s in the given float array, starting from the
-     * specified offset, to the current position and increase the position by
-     * the number of <code>float</code>s written.
+     * Writes floats from the given float array, starting from the specified
+     * offset, to the current position and increases the position by the number
+     * of floats written.
      * 
      * @param src
-     *            The source float array
+     *            the source float array.
      * @param off
-     *            The offset of float array, must be no less than zero and no
-     *            greater than <code>src.length</code>
+     *            the offset of float array, must not be negative and not
+     *            greater than {@code src.length}.
      * @param len
-     *            The number of <code>float</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 floats 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 FloatBuffer put(float[] 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();
         }
 
@@ -489,20 +460,20 @@
     }
 
     /**
-     * Writes all the remaining <code>float</code>s of the <code>src</code>
-     * float buffer to this buffer's current position, and increase both
-     * buffers' position by the number of <code>float</code>s copied.
+     * Writes all the remaining floats of the {@code src} float buffer to this
+     * buffer's current position, and increases both buffers' position by the
+     * number of floats copied.
      * 
      * @param src
-     *            The source float buffer
-     * @return This buffer
+     *            the source float 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 FloatBuffer put(FloatBuffer src) {
         if (src == this) {
@@ -518,44 +489,42 @@
     }
 
     /**
-     * Write a float to the specified index of this buffer and the position is
-     * not changed.
+     * Writes a float 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 not be negative and less than the limit.
      * @param f
-     *            The float to write
-     * @return This buffer
+     *            the float 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 FloatBuffer put(int index, float f);
 
     /**
-     * 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'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 FloatBuffer slice();
 
     /**
-     * Returns a string represents the state of this float buffer.
+     * Returns a string representing the state of this float buffer.
      * 
-     * @return A string represents the state of this float buffer.
+     * @return a string representing the state of this float buffer.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/IntBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/IntBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/IntBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/IntBuffer.java Mon Apr 27 10:23:36 2009
@@ -18,7 +18,7 @@
 package java.nio;
 
 /**
- * A buffer of <code>int</code>s.
+ * A buffer of ints.
  * <p>
  * A int buffer can be created in either of the following ways:
  * <ul>
@@ -28,18 +28,17 @@
  * <li>Use {@link java.nio.ByteBuffer#asIntBuffer() ByteBuffer.asIntBuffer} to
  * create a int buffer based on a byte buffer.</li>
  * </ul>
- * </p>
  */
 public abstract class IntBuffer extends Buffer implements Comparable<IntBuffer> {
 
     /**
-     * Creates a int buffer based on a new allocated int array.
+     * Creates an int buffer based on a newly allocated int array.
      * 
      * @param capacity
-     *            The capacity of the new buffer
-     * @return The created int buffer
+     *            the capacity of the new buffer.
+     * @return the created int buffer.
      * @throws IllegalArgumentException
-     *             If <code>capacity</code> is less than zero
+     *             if {@code capacity} is less than zero.
      */
     public static IntBuffer allocate(int capacity) {
         if (capacity < 0) {
@@ -52,36 +51,33 @@
      * Creates a new int buffer by wrapping the given int 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 int array which the new buffer will be based on
-     * @return The created int buffer
+     *            the int array which the new buffer will be based on.
+     * @return the created int buffer.
      */
     public static IntBuffer wrap(int[] array) {
         return wrap(array, 0, array.length);
     }
 
     /**
-     * Creates new a int buffer by wrapping the given int array.
+     * Creates a new int buffer by wrapping the given int 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 int array which the new buffer will be based on
+     *            the int 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 int buffer
+     *            the length, must not be negative and not greater than
+     *            {@code array.length - start}.
+     * @return the created int 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 IntBuffer wrap(int[] array, int start, int len) {
         if (array == null) {
@@ -99,23 +95,23 @@
     }
 
     /**
-     * Constructs a <code>IntBuffer</code> with given capacity.
-     * 
+     * Constructs a {@code IntBuffer} with given capacity.
+     *
      * @param capacity
-     *            The capacity of the buffer
+     *            the capacity of the buffer.
      */
     IntBuffer(int capacity) {
         super(capacity);
     }
 
     /**
-     * Returns the int array which this buffer is based on, if there's one.
+     * Returns the int array which this buffer is based on, if there is one.
      * 
-     * @return The int array which this buffer is based on
+     * @return the int 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[] array() {
         return protectedArray();
@@ -123,65 +119,60 @@
 
     /**
      * Returns the offset of the int 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 int array which this buffer is based on
+     *
+     * @return the offset of the int 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>
+     * 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 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 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 IntBuffer asReadOnlyBuffer();
 
     /**
      * Compacts this int buffer.
      * <p>
-     * The remaining <code>int</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 ints 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 IntBuffer compact();
 
     /**
-     * Compare the remaining <code>int</code>s of this buffer to another int
-     * buffer's remaining <code>int</code>s.
+     * Compares the remaining ints of this buffer to another int buffer's
+     * remaining ints.
      * 
      * @param otherBuffer
-     *            Another int 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 int 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 int buffer
+     *                if {@code other} is not an int buffer.
      */
     public int compareTo(IntBuffer otherBuffer) {
         int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -203,36 +194,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. The duplicated 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 duplicated buffer that shares content with this buffer.
+     *
+     * @return a duplicated buffer that shares its content with this buffer.
      */
     public abstract IntBuffer duplicate();
 
     /**
-     * Tests whether this int buffer equals to another object.
+     * Checks whether this int buffer is equal to another object.
      * <p>
-     * If <code>other</code> is not a int buffer, then false is returned.
-     * </p>
-     * <p>
-     * Two int buffers are equals if, and only if, their remaining
-     * <code>int</code>s are exactly the same. Position, limit, capacity and
-     * mark are not considered.
-     * </p>
-     * 
+     * If {@code other} is not a int buffer then {@code false} is returned. Two
+     * int buffers are equal if and only if their remaining ints are exactly the
+     * same. Position, limit, capacity and mark are not considered.
+     *
      * @param other
-     *            the object to be compared against
-     * @return Whether this int buffer equals to another object.
+     *            the object to compare with this int buffer.
+     * @return {@code true} if this int buffer is equal to {@code other},
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object other) {
@@ -256,54 +242,49 @@
     }
 
     /**
-     * Returns the int at the current position and increase the position by 1.
+     * Returns the int at the current position and increases the position by 1.
      * 
-     * @return The int at the current position.
+     * @return the int 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 int get();
 
     /**
-     * Reads <code>int</code>s from the current position into the specified
-     * int array and increase the position by the number of <code>int</code>s
-     * read.
+     * Reads ints from the current position into the specified int array and
+     * increases the position by the number of ints 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 int array
-     * @return This buffer
+     *            the destination int 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 IntBuffer get(int[] dest) {
         return get(dest, 0, dest.length);
     }
 
     /**
-     * Reads <code>int</code>s from the current position into the specified
-     * int array, starting from the specified offset, and increase the position
-     * by the number of <code>int</code>s read.
+     * Reads ints from the current position into the specified int array,
+     * starting from the specified offset, and increases the position by the
+     * number of ints read.
      * 
      * @param dest
-     *            The target int array
+     *            the target int array.
      * @param off
-     *            The offset of the int array, must be no less than zero and no
-     *            greater than <code>dest.length</code>
+     *            the offset of the int array, must not be negative and not
+     *            greater than {@code dest.length}.
      * @param len
-     *            The number of <code>int</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 ints 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 IntBuffer get(int[] dest, int off, int len) {
         int length = dest.length;
@@ -320,35 +301,31 @@
     }
 
     /**
-     * Returns a int at the specified index, and the position is not changed.
+     * Returns an int 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 int at the specified index.
+     *            the index, must not be negative and less than limit.
+     * @return an int at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      */
     public abstract int get(int index);
 
     /**
-     * Returns whether this buffer is based on a int array and is read/write.
-     * <p>
-     * If this buffer is readonly, then false is returned.
-     * </p>
-     * 
-     * @return Whether this buffer is based on a int array and is read/write.
+     * Indicates whether this buffer is based on a int array and is read/write.
+     *
+     * @return {@code true} if this buffer is based on a int array and provides
+     *         read/write access, {@code false} otherwise.
      */
     public final boolean hasArray() {
         return protectedHasArray();
     }
 
     /**
-     * Hash code is calculated from the remaining <code>int</code>s.
-     * <p>
-     * Position, limit, capacity and mark don't affect the hash code.
-     * </p>
-     * 
-     * @return The hash code calculated from the remaining <code>int</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 ints.
      */
     @Override
     public int hashCode() {
@@ -361,108 +338,103 @@
     }
 
     /**
-     * Returns true if this buffer is direct.
+     * 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 int buffer is direct, if it is based on a byte buffer and the byte
+     * An int 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>int</code>s from/to <code>byte</code>s.
+     * Returns the byte order used by this buffer when converting ints 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>int</code>s from/to <code>byte</code>s.
+     *
+     * @return the byte order used by this buffer when converting ints 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()}.
+     *
+     * @return see {@code array()}
      */
     abstract int[] 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()}.
+     *
+     * @return see {@code 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()}.
+     *
+     * @return see {@code hasArray()}
      */
     abstract boolean protectedHasArray();
 
     /**
-     * Writes the given int to the current position and increase the position by
-     * 1.
+     * Writes the given int to the current position and increases the position
+     * by 1.
      * 
      * @param i
-     *            The int to write
-     * @return This buffer
+     *            the int 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 IntBuffer put(int i);
 
     /**
-     * Writes <code>int</code>s in the given int array to the current
-     * position and increase the position by the number of <code>int</code>s
-     * written.
+     * Writes ints from the given int array to the current position and
+     * increases the position by the number of ints 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 int array
-     * @return This buffer
+     *            the source int 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 IntBuffer put(int[] src) {
         return put(src, 0, src.length);
     }
 
     /**
-     * Writes <code>int</code>s in the given int array, starting from the
-     * specified offset, to the current position and increase the position by
-     * the number of <code>int</code>s written.
+     * Writes ints from the given int array, starting from the specified offset,
+     * to the current position and increases the position by the number of ints
+     * written.
      * 
      * @param src
-     *            The source int array
+     *            the source int array.
      * @param off
-     *            The offset of int array, must be no less than zero and no
-     *            greater than <code>src.length</code>
+     *            the offset of int array, must not be negative and not greater
+     *            than {@code src.length}.
      * @param len
-     *            The number of <code>int</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 ints 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 IntBuffer put(int[] src, int off, int len) {
         int length = src.length;
@@ -480,20 +452,20 @@
     }
 
     /**
-     * Writes all the remaining <code>int</code>s of the <code>src</code>
-     * int buffer to this buffer's current position, and increase both buffers'
-     * position by the number of <code>int</code>s copied.
+     * Writes all the remaining ints of the {@code src} int buffer to this
+     * buffer's current position, and increases both buffers' position by the
+     * number of ints copied.
      * 
      * @param src
-     *            The source int buffer
-     * @return This buffer
+     *            the source int 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 IntBuffer put(IntBuffer src) {
         if (src == this) {
@@ -509,44 +481,42 @@
     }
 
     /**
-     * Write a int to the specified index of this buffer and the position is not
+     * Write a int 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 not be negative and less than the limit.
      * @param i
-     *            The int to write
-     * @return This buffer
+     *            the int 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 IntBuffer put(int index, int i);
 
     /**
-     * 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'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 IntBuffer slice();
 
     /**
-     * Returns a string represents the state of this int buffer.
+     * Returns a string represents of the state of this int buffer.
      * 
-     * @return A string represents the state of this int buffer.
+     * @return a string represents of the state of this int buffer.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/InvalidMarkException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/InvalidMarkException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/InvalidMarkException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/InvalidMarkException.java Mon Apr 27 10:23:36 2009
@@ -17,16 +17,15 @@
 package java.nio;
 
 /**
- * A <code>InvalidMarkException</code> is thrown when <code>reset()</code>
- * is called on a buffer, but there is no mark set previously.
- * 
+ * An {@code InvalidMarkException} is thrown when {@code reset()} is called on a
+ * buffer, but no mark has been set previously.
  */
 public class InvalidMarkException extends IllegalStateException {
 
     private static final long serialVersionUID = 1698329710438510774L;
 
     /**
-     * Constructs an <code>InvalidMarkException</code>.
+     * Constructs an {@code InvalidMarkException}.
      */
     public InvalidMarkException() {
         super();

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongBuffer.java Mon Apr 27 10:23:36 2009
@@ -18,7 +18,7 @@
 package java.nio;
 
 /**
- * A buffer of <code>long</code>s.
+ * A buffer of longs.
  * <p>
  * A long buffer can be created in either of the following ways:
  * <ul>
@@ -29,19 +29,18 @@
  * <li>Use {@link java.nio.ByteBuffer#asLongBuffer() ByteBuffer.asLongBuffer}
  * to create a long buffer based on a byte buffer.</li>
  * </ul>
- * </p>
  */
 public abstract class LongBuffer extends Buffer implements
         Comparable<LongBuffer> {
 
     /**
-     * Creates a long buffer based on a new allocated long array.
+     * Creates a long buffer based on a newly allocated long array.
      * 
      * @param capacity
-     *            The capacity of the new buffer
-     * @return The created long buffer
+     *            the capacity of the new buffer.
+     * @return the created long buffer.
      * @throws IllegalArgumentException
-     *             If <code>capacity</code> is less than zero
+     *             if {@code capacity} is less than zero.
      */
     public static LongBuffer allocate(int capacity) {
         if (capacity < 0) {
@@ -54,36 +53,33 @@
      * Creates a new long buffer by wrapping the given long 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 long array which the new buffer will be based on
-     * @return The created long buffer
+     *            the long array which the new buffer will be based on.
+     * @return the created long buffer.
      */
     public static LongBuffer wrap(long[] array) {
         return wrap(array, 0, array.length);
     }
 
     /**
-     * Creates new a long buffer by wrapping the given long array.
+     * Creates a new long buffer by wrapping the given long 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 long array which the new buffer will be based on
+     *            the long 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 long buffer
+     *            the length, must not be negative and not greater than
+     *            {@code array.length - start}.
+     * @return the created long 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 LongBuffer wrap(long[] array, int start, int len) {
         if (array == null) {
@@ -101,8 +97,8 @@
     }
 
     /**
-     * Constructs a <code>LongBuffer</code> with given capacity.
-     * 
+     * Constructs a {@code LongBuffer} with given capacity.
+     *
      * @param capacity
      *            The capacity of the buffer
      */
@@ -111,13 +107,13 @@
     }
 
     /**
-     * Returns the long array which this buffer is based on, if there's one.
+     * Returns the long array which this buffer is based on, if there is one.
      * 
-     * @return The long array which this buffer is based on
+     * @return the long 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 long[] array() {
         return protectedArray();
@@ -125,65 +121,60 @@
 
     /**
      * Returns the offset of the long 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 long array which this buffer is based on
+     * The offset is the index of the array and corresponds to the zero position
+     * of the buffer.
+     *
+     * @return the offset of the long 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 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 LongBuffer asReadOnlyBuffer();
 
     /**
      * Compacts this long buffer.
      * <p>
-     * The remaining <code>long</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 longs 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 LongBuffer compact();
 
     /**
-     * Compare the remaining <code>long</code>s of this buffer to another
-     * long buffer's remaining <code>long</code>s.
+     * Compare the remaining longs of this buffer to another long buffer's
+     * remaining longs.
      * 
      * @param otherBuffer
-     *            Another long 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 long 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 long buffer
+     *                if {@code otherBuffer} is not a long buffer.
      */
     public int compareTo(LongBuffer otherBuffer) {
         int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
@@ -205,36 +196,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. The duplicated buffer's read-only property and byte order
+     * are 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 LongBuffer duplicate();
 
     /**
-     * Tests whether this long buffer equals to another object.
-     * <p>
-     * If <code>other</code> is not a long buffer, then false is returned.
-     * </p>
+     * Checks whether this long buffer is equal to another object.
      * <p>
-     * Two long buffers are equals if, and only if, their remaining
-     * <code>long</code>s are exactly the same. Position, limit, capacity and
-     * mark are not considered.
-     * </p>
-     * 
+     * If {@code other} is not a long buffer then {@code false} is returned. Two
+     * long buffers are equal if and only if their remaining longs are exactly
+     * the same. Position, limit, capacity and mark are not considered.
+     *
      * @param other
-     *            the object to be compared against
-     * @return Whether this long buffer equals to another object.
+     *            the object to compare with this long buffer.
+     * @return {@code true} if this long buffer is equal to {@code other},
+     *         {@code false} otherwise.
      */
     @Override
     public boolean equals(Object other) {
@@ -260,52 +246,47 @@
     /**
      * Returns the long at the current position and increase the position by 1.
      * 
-     * @return The long at the current position.
+     * @return the long 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 long get();
 
     /**
-     * Reads <code>long</code>s from the current position into the specified
-     * long array and increase the position by the number of <code>long</code>s
-     * read.
+     * Reads longs from the current position into the specified long array and
+     * increases the position by the number of longs 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 long array
-     * @return This buffer
+     *            the destination long 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 LongBuffer get(long[] dest) {
         return get(dest, 0, dest.length);
     }
 
     /**
-     * Reads <code>long</code>s from the current position into the specified
-     * long array, starting from the specified offset, and increase the position
-     * by the number of <code>long</code>s read.
+     * Reads longs from the current position into the specified long array,
+     * starting from the specified offset, and increase the position by the
+     * number of longs read.
      * 
      * @param dest
-     *            The target long array
+     *            the target long array.
      * @param off
-     *            The offset of the long array, must be no less than zero and no
-     *            greater than <code>dest.length</code>
+     *            the offset of the long array, must not be negative and not
+     *            greater than {@code dest.length}.
      * @param len
-     *            The number of <code>long</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 longs 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 LongBuffer get(long[] dest, int off, int len) {
         int length = dest.length;
@@ -323,35 +304,31 @@
     }
 
     /**
-     * Returns a long at the specified index, and the position is not changed.
+     * Returns the long 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 long at the specified index.
+     *            the index, must not be negative and less than limit.
+     * @return the long at the specified index.
      * @exception IndexOutOfBoundsException
-     *                If index is invalid
+     *                if index is invalid.
      */
     public abstract long get(int index);
 
     /**
-     * Returns whether this buffer is based on a long array and is read/write.
-     * <p>
-     * If this buffer is readonly, then false is returned.
-     * </p>
-     * 
-     * @return Whether this buffer is based on a long array and is read/write.
+     * Indicates whether this buffer is based on a long array and is read/write.
+     *
+     * @return {@code true} if this buffer is based on a long array and provides
+     *         read/write access, {@code false} otherwise.
      */
     public final boolean hasArray() {
         return protectedHasArray();
     }
 
     /**
-     * Hash code is calculated from the remaining <code>long</code>s.
-     * <p>
-     * Position, limit, capacity and mark don't affect the hash code.
-     * </p>
-     * 
-     * @return The hash code calculated from the remaining <code>long</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 longs.
      */
     @Override
     public int hashCode() {
@@ -366,112 +343,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 long buffer is direct, if it is based on a byte buffer and the byte
+     * A long 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>long</code>s from/to <code>byte</code>s.
+     * Returns the byte order used by this buffer when converting longs 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>long</code>s from/to <code>byte</code>s.
+     *
+     * @return the byte order used by this buffer when converting longs 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()}.
+     *
+     * @return see {@code array()}
      */
     abstract long[] 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()}.
+     *
+     * @return see {@code 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()}.
+     *
+     * @return see {@code hasArray()}
      */
     abstract boolean protectedHasArray();
 
     /**
-     * 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 1.
      * 
      * @param l
-     *            The long to write
-     * @return This buffer
+     *            the long 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 LongBuffer put(long l);
 
     /**
-     * Writes <code>long</code>s in the given long array to the current
-     * position and increase the position by the number of <code>long</code>s
-     * written.
+     * Writes longs from the given long array to the current position and
+     * increases the position by the number of longs 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 long array
-     * @return This buffer
+     *            the source long 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 LongBuffer put(long[] src) {
         return put(src, 0, src.length);
     }
 
     /**
-     * Writes <code>long</code>s in the given long array, starting from the
-     * specified offset, to the current position and increase the position by
-     * the number of <code>long</code>s written.
+     * Writes longs from the given long array, starting from the specified
+     * offset, to the current position and increases the position by the number
+     * of longs written.
      * 
      * @param src
-     *            The source long array
+     *            the source long array.
      * @param off
-     *            The offset of long array, must be no less than zero and no
-     *            greater than <code>src.length</code>
+     *            the offset of long array, must not be negative and not greater
+     *            than {@code src.length}.
      * @param len
-     *            The number of <code>long</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 longs 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 LongBuffer put(long[] src, int off, int len) {
         int length = src.length;
@@ -489,20 +457,20 @@
     }
 
     /**
-     * Writes all the remaining <code>long</code>s of the <code>src</code>
-     * long buffer to this buffer's current position, and increase both buffers'
-     * position by the number of <code>long</code>s copied.
+     * Writes all the remaining longs of the {@code src} long buffer to this
+     * buffer's current position, and increases both buffers' position by the
+     * number of longs copied.
      * 
      * @param src
-     *            The source long buffer
-     * @return This buffer
+     *            the source long 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 LongBuffer put(LongBuffer src) {
         if (src == this) {
@@ -518,44 +486,42 @@
     }
 
     /**
-     * Write a long to the specified index of this buffer and the position is
-     * not changed.
+     * Writes a long 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 not be negative and less than the limit.
      * @param l
-     *            The long to write
-     * @return This buffer
+     *            the long 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 LongBuffer put(int index, long l);
 
     /**
-     * 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'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 LongBuffer slice();
 
     /**
-     * Returns a string represents the state of this long buffer.
+     * Returns a string representing the state of this long buffer.
      * 
-     * @return A string represents the state of this long buffer.
+     * @return a string representing the state of this long buffer.
      */
     @Override
     public String toString() {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongToByteBufferAdapter.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongToByteBufferAdapter.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongToByteBufferAdapter.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/LongToByteBufferAdapter.java Mon Apr 27 10:23:36 2009
@@ -30,7 +30,7 @@
  * The adapter extends Buffer, thus has its own position and limit.</li>
  * </ul>
  * </p>
- * 
+ *
  */
 final class LongToByteBufferAdapter extends LongBuffer implements DirectBuffer {
 

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/MappedByteBuffer.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/MappedByteBuffer.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/MappedByteBuffer.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/MappedByteBuffer.java Mon Apr 27 10:23:36 2009
@@ -22,21 +22,18 @@
 import org.apache.harmony.nio.internal.DirectBuffer;
 
 /**
- * <code>MappedByteBuffer</code> is a special kind of direct byte buffer,
- * which maps a region of file to memory.
+ * {@code MappedByteBuffer} is a special kind of direct byte buffer which maps a
+ * region of file to memory.
  * <p>
- * <code>MappedByteBuffer</code> can be created by calling
+ * {@code MappedByteBuffer} can be created by calling
  * {@link java.nio.channels.FileChannel#map(java.nio.channels.FileChannel.MapMode, long, long) FileChannel.map}.
  * Once created, the mapping between the byte buffer and the file region remains
  * valid until the byte buffer is garbage collected.
- * </p>
  * <p>
- * All or part of a <code>MappedByteBuffer</code>'s content may change or
- * become inaccessible at any time, since the mapped file region can be modified
- * by another thread or process at any time. If this happens, the behavior of
- * the <code>MappedByteBuffer</code> is undefined.
- * </p>
- * 
+ * All or part of a {@code MappedByteBuffer}'s content may change or become
+ * inaccessible at any time, since the mapped file region can be modified by
+ * another thread or process at any time. If this happens, the behavior of the
+ * {@code MappedByteBuffer} is undefined.
  */
 public abstract class MappedByteBuffer extends ByteBuffer {
 
@@ -71,9 +68,12 @@
     }
 
     /**
-     * Returns true if this buffer's content is loaded.
+     * Indicates whether this buffer's content is loaded. If the result is true
+     * there is a high probability that the whole buffer memory is currently
+     * loaded in RAM. If it is false it is unsure if it is loaded or not.
      * 
-     * @return True if this buffer's content is loaded.
+     * @return {@code true} if this buffer's content is loaded, {@code false}
+     *         otherwise.
      */
     public final boolean isLoaded() {
         return ((MappedPlatformAddress) ((DirectBuffer) wrapped)
@@ -81,9 +81,10 @@
     }
 
     /**
-     * Loads this buffer's content into memory.
+     * Loads this buffer's content into memory but it is not guaranteed to
+     * succeed.
      * 
-     * @return This buffer
+     * @return this buffer.
      */
     public final MappedByteBuffer load() {
         ((MappedPlatformAddress) ((DirectBuffer) wrapped).getBaseAddress())
@@ -92,12 +93,12 @@
     }
 
     /**
-     * Writes all changes of the buffer to the mapped file.
+     * Writes all changes of the buffer to the mapped file. If the mapped file
+     * is stored on a local device, it is guaranteed that the changes are
+     * written to the file. No such guarantee is given if the file is located on
+     * a remote device.
      * 
-     * All changes must be written by invoking this method if the mapped file
-     * exists on the local device, otherwise the action can not be specified.
-     * 
-     * @return This buffer
+     * @return this buffer.
      */
     public final MappedByteBuffer force() {
         if (mapMode == IMemorySystem.MMAP_READ_WRITE) {

Modified: harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ReadOnlyBufferException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ReadOnlyBufferException.java?rev=768919&r1=768918&r2=768919&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ReadOnlyBufferException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/nio/src/main/java/common/java/nio/ReadOnlyBufferException.java Mon Apr 27 10:23:36 2009
@@ -17,16 +17,15 @@
 package java.nio;
 
 /**
- * A <code>ReadOnlyBufferException</code> is thrown when some write operation
- * is called on a readonly buffer.
- * 
+ * A {@code ReadOnlyBufferException} is thrown when some write operation is
+ * called on a read-only buffer.
  */
 public class ReadOnlyBufferException extends UnsupportedOperationException {
 
     private static final long serialVersionUID = -1210063976496234090L;
 
     /**
-     * Constructs a <code>ReadOnlyBufferException</code>.
+     * Constructs a {@code ReadOnlyBufferException}.
      */
     public ReadOnlyBufferException() {
         super();



Mime
View raw message