diff --git a/src/main/java/org/jboss/netty/channel/socket/nio/NioDatagramChannelConfig.java b/src/main/java/org/jboss/netty/channel/socket/nio/NioDatagramChannelConfig.java
index 54235f69a1..acf4fc2079 100644
--- a/src/main/java/org/jboss/netty/channel/socket/nio/NioDatagramChannelConfig.java
+++ b/src/main/java/org/jboss/netty/channel/socket/nio/NioDatagramChannelConfig.java
@@ -26,6 +26,7 @@ import java.nio.ByteBuffer;
 import java.nio.channels.WritableByteChannel;
 
 import org.jboss.netty.channel.AdaptiveReceiveBufferSizePredictor;
+import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelConfig;
 import org.jboss.netty.channel.ReceiveBufferSizePredictor;
 import org.jboss.netty.channel.socket.DatagramChannel;
@@ -62,10 +63,36 @@ import org.jboss.netty.channel.socket.DatagramChannelConfig;
  */
 public interface NioDatagramChannelConfig extends DatagramChannelConfig {
 
+    /**
+     * Returns the high water mark of the write buffer.  If the number of bytes
+     * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
+     * will start to return {@code true}.
+     */
     int getWriteBufferHighWaterMark();
+
+    /**
+     * Sets the high water mark of the write buffer.  If the number of bytes
+     * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
+     * will start to return {@code true}.
+     */
     void setWriteBufferHighWaterMark(int writeBufferHighWaterMark);
 
+    /**
+     * Returns the low water mark of the write buffer.  Once the number of bytes
+     * queued in the write buffer exceeded the
+     * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
+     * dropped down below this value, {@link Channel#isWritable()} will return
+     * {@code false} again.
+     */
     int getWriteBufferLowWaterMark();
+
+    /**
+     * Sets the low water mark of the write buffer.  Once the number of bytes
+     * queued in the write buffer exceeded the
+     * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
+     * dropped down below this value, {@link Channel#isWritable()} will return
+     * {@code false} again.
+     */
     void setWriteBufferLowWaterMark(int writeBufferLowWaterMark);
 
     /**
diff --git a/src/main/java/org/jboss/netty/channel/socket/nio/NioSocketChannelConfig.java b/src/main/java/org/jboss/netty/channel/socket/nio/NioSocketChannelConfig.java
index af227df98e..ba28a1a33b 100644
--- a/src/main/java/org/jboss/netty/channel/socket/nio/NioSocketChannelConfig.java
+++ b/src/main/java/org/jboss/netty/channel/socket/nio/NioSocketChannelConfig.java
@@ -26,6 +26,7 @@ import java.nio.ByteBuffer;
 import java.nio.channels.WritableByteChannel;
 
 import org.jboss.netty.channel.AdaptiveReceiveBufferSizePredictor;
+import org.jboss.netty.channel.Channel;
 import org.jboss.netty.channel.ChannelConfig;
 import org.jboss.netty.channel.ReceiveBufferSizePredictor;
 import org.jboss.netty.channel.socket.SocketChannel;
@@ -63,10 +64,36 @@ import org.jboss.netty.channel.socket.SocketChannelConfig;
  */
 public interface NioSocketChannelConfig extends SocketChannelConfig {
 
+    /**
+     * Returns the high water mark of the write buffer.  If the number of bytes
+     * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
+     * will start to return {@code true}.
+     */
     int getWriteBufferHighWaterMark();
+
+    /**
+     * Sets the high water mark of the write buffer.  If the number of bytes
+     * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
+     * will start to return {@code true}.
+     */
     void setWriteBufferHighWaterMark(int writeBufferHighWaterMark);
 
+    /**
+     * Returns the low water mark of the write buffer.  Once the number of bytes
+     * queued in the write buffer exceeded the
+     * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
+     * dropped down below this value, {@link Channel#isWritable()} will return
+     * {@code false} again.
+     */
     int getWriteBufferLowWaterMark();
+
+    /**
+     * Sets the low water mark of the write buffer.  Once the number of bytes
+     * queued in the write buffer exceeded the
+     * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
+     * dropped down below this value, {@link Channel#isWritable()} will return
+     * {@code false} again.
+     */
     void setWriteBufferLowWaterMark(int writeBufferLowWaterMark);
 
     /**