More JavaDoc

src/main/java/org/jboss/netty/buffer/AbstractChannelBuffer.java

@@ -32,6 +32,7 @@ import java.util.NoSuchElementException;
 
 
 /**
+ * Skeletal implementation of a buffer.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)

src/main/java/org/jboss/netty/buffer/BigEndianHeapChannelBuffer.java

@@ -26,6 +26,7 @@ import java.nio.ByteOrder;
 
 
 /**
+ * Big-endian Java heap buffer.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)

src/main/java/org/jboss/netty/buffer/ByteBufferBackedChannelBuffer.java

@@ -33,7 +33,15 @@ import java.nio.channels.GatheringByteChannel;
 import java.nio.channels.ScatteringByteChannel;
 import java.nio.charset.UnsupportedCharsetException;
 
-
+/**
+ * NIO direct buffer based buffer.
+ *
+ * @author The Netty Project (netty-dev@lists.jboss.org)
+ * @author Trustin Lee (tlee@redhat.com)
+ *
+ * @version $Rev$, $Date$
+ *
+ */
 public class ByteBufferBackedChannelBuffer extends AbstractChannelBuffer {
 
     private final ByteBuffer buffer;

src/main/java/org/jboss/netty/buffer/ChannelBuffer.java

@@ -31,7 +31,7 @@ import java.nio.channels.GatheringByteChannel;
 import java.nio.channels.ScatteringByteChannel;
 
 /**
- * A random and sequential accessible sequence of zero or more bytes (octets).
+ * Random and sequential accessible sequence of zero or more bytes (octets).
  * This interface provides an abstract view for one or more primitive byte
  * arrays ({@code byte[]}) and {@linkplain ByteBuffer NIO buffers}.
  *

src/main/java/org/jboss/netty/buffer/ChannelBufferInputStream.java

@@ -29,6 +29,15 @@ import java.io.IOException;
 import java.io.InputStream;
 
 /**
+ * {@link InputStream} which reads data from a {@link ChannelBuffer}.
+ * <p>
+ * A read operation against this stream will occur at the {@code readerIndex}
+ * of its underlying buffer and the {@code readerIndex} will increase during
+ * the read operation.
+ * <p>
+ * This stream implements {@link DataInput} for your convenience.
+ * The endianness of the stream is not always big endian but depends on
+ * the endianness of the underlying buffer.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -44,10 +53,24 @@ public class ChannelBufferInputStream extends InputStream implements DataInput {
     private final int startIndex;
     private final int endIndex;
 
+    /**
+     * Creates a new stream which reads data from the specified {@code buffer}
+     * starting at the current {@code readerIndex} and ending at the current
+     * {@code writerIndex}.
+     */
     public ChannelBufferInputStream(ChannelBuffer buffer) {
         this(buffer, buffer.readableBytes());
     }
 
+    /**
+     * Creates a new stream which reads data from the specified {@code buffer}
+     * starting at the current {@code readerIndex} and ending at
+     * {@code readerIndex + length}.
+     *
+     * @throws IndexOutOfBoundsException
+     *         if {@code readerIndex + length} is greater than
+     *            {@code writerIndex}
+     */
     public ChannelBufferInputStream(ChannelBuffer buffer, int length) {
         if (buffer == null) {
             throw new NullPointerException("buffer");
@@ -62,6 +85,9 @@ public class ChannelBufferInputStream extends InputStream implements DataInput {
         buffer.markReaderIndex();
     }
 
+    /**
+     * Returns the number of read bytes by this stream so far.
+     */
     public int readBytes() {
         return buffer.readerIndex() - startIndex;
     }

src/main/java/org/jboss/netty/buffer/ChannelBufferOutputStream.java

@@ -28,6 +28,15 @@ import java.io.IOException;
 import java.io.OutputStream;
 
 /**
+ * {@link OutputStream} which writes data to a {@link ChannelBuffer}.
+ * <p>
+ * A write operation against this stream will occur at the {@code writerIndex}
+ * of its underlying buffer and the {@code writerIndex} will increase during
+ * the write operation.
+ * <p>
+ * This stream implements {@link DataOutput} for your convenience.
+ * The endianness of the stream is not always big endian but depends on
+ * the endianness of the underlying buffer.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
@@ -42,6 +51,9 @@ public class ChannelBufferOutputStream extends OutputStream implements DataOutpu
     private final ChannelBuffer buffer;
     private final DataOutputStream utf8out = new DataOutputStream(this);
 
+    /**
+     * Creates a new stream which writes data to the specified {@code buffer}.
+     */
     public ChannelBufferOutputStream(ChannelBuffer buffer) {
         if (buffer == null) {
             throw new NullPointerException("buffer");
@@ -118,6 +130,9 @@ public class ChannelBufferOutputStream extends OutputStream implements DataOutpu
         utf8out.writeUTF(s);
     }
 
+    /**
+     * Returns the buffer where this stream is writing data.
+     */
     public ChannelBuffer buffer() {
         return buffer;
     }

src/main/java/org/jboss/netty/buffer/ChannelBuffers.java

@@ -30,7 +30,7 @@ import java.nio.charset.UnsupportedCharsetException;
 
 /**
  * Creates a new {@link ChannelBuffer} by allocating new space or by wrapping
- * or copying existing byte arrays.
+ * or copying existing byte arrays, byte buffer and string.
  *
  * <h3>Use static import</h3>
  * This classes is intended to be used with Java 5 static import statement:
@@ -60,9 +60,9 @@ import java.nio.charset.UnsupportedCharsetException;
  * <h3>Creating a wrapped buffer</h3>
  *
  * Wrapped buffer is a buffer which is a view of one or more existing
- * byte arrays or byte buffer.  Any changes in the content of the original
- * array or buffer will be reflected in the wrapped buffer.  Various wrapper
- * methods are provided and their name is all {@code wrappedBuffer()}.
+ * byte arrays, byte buffer and string.  Any changes in the content of the
+ * original array or buffer will be reflected in the wrapped buffer.  Various
+ * wrapper methods are provided and their name is all {@code wrappedBuffer()}.
  * You might want to take a look at this method closely if you want to create
  * a buffer which is composed of more than one array to reduce the number of
  * memory copy.

src/main/java/org/jboss/netty/buffer/CompositeChannelBuffer.java

@@ -36,6 +36,8 @@ import java.util.List;
 
 
 /**
+ * Virtual buffer which shows multiple buffers as a single merged buffer.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *

src/main/java/org/jboss/netty/buffer/DuplicatedChannelBuffer.java

@@ -32,6 +32,9 @@ import java.nio.channels.ScatteringByteChannel;
 
 
 /**
+ * Derived buffer which simply forwards all data access requests to its
+ * parent.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *

src/main/java/org/jboss/netty/buffer/DynamicChannelBuffer.java

@@ -32,6 +32,8 @@ import java.nio.channels.ScatteringByteChannel;
 
 
 /**
+ * Dynamic capacity buffer which increases its capacity as needed.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *

src/main/java/org/jboss/netty/buffer/HeapChannelBuffer.java

@@ -33,6 +33,7 @@ import java.nio.channels.ScatteringByteChannel;
 import java.nio.charset.UnsupportedCharsetException;
 
 /**
+ * Skeletal implementation for Java heap buffers.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)

src/main/java/org/jboss/netty/buffer/LittleEndianHeapChannelBuffer.java

@@ -26,6 +26,7 @@ import java.nio.ByteOrder;
 
 
 /**
+ * Little-endian Java heap buffer.
  *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)

src/main/java/org/jboss/netty/buffer/ReadOnlyChannelBuffer.java

@@ -30,6 +30,15 @@ import java.nio.ByteOrder;
 import java.nio.channels.GatheringByteChannel;
 import java.nio.channels.ScatteringByteChannel;
 
+/**
+ * Derived buffer which forbids any write requests to its parent.
+ *
+ * @author The Netty Project (netty-dev@lists.jboss.org)
+ * @author Trustin Lee (tlee@redhat.com)
+ *
+ * @version $Rev$, $Date$
+ *
+ */
 public class ReadOnlyChannelBuffer extends AbstractChannelBuffer implements WrappedChannelBuffer {
 
     private final ChannelBuffer buffer;

src/main/java/org/jboss/netty/buffer/SlicedChannelBuffer.java

@@ -32,6 +32,8 @@ import java.nio.channels.ScatteringByteChannel;
 
 
 /**
+ * Derived buffer which exposes its parent's sub-region only.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *

src/main/java/org/jboss/netty/buffer/TruncatedChannelBuffer.java

@@ -32,6 +32,8 @@ import java.nio.channels.ScatteringByteChannel;
 
 
 /**
+ * Derived buffer which hides its parent's tail data beyond a certain index.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *

src/main/java/org/jboss/netty/buffer/WrappedChannelBuffer.java

@@ -23,6 +23,8 @@
 package org.jboss.netty.buffer;
 
 /**
+ * Common interface for buffer wrappers and derived buffers.
+ *
  * @author The Netty Project (netty-dev@lists.jboss.org)
  * @author Trustin Lee (tlee@redhat.com)
  *
@@ -30,5 +32,8 @@ package org.jboss.netty.buffer;
  *
  */
 public interface WrappedChannelBuffer extends ChannelBuffer {
+    /**
+     * Returns this buffer's parent that this buffer is wrapping.
+     */
     ChannelBuffer unwrap();
 }