Update javadocs to highlight that derived buffers will not increment …

…the reference count.

Motivation:

We not explain the derived buffers will not retain the parent buffer.

Modifications:

Add docs.

Result:

Correctly document behaviour

buffer/src/main/java/io/netty/buffer/ByteBuf.java

@@ -201,6 +201,9 @@
  * <p>
  * In case a completely fresh copy of an existing buffer is required, please
  * call {@link #copy()} method instead.
+ * <p>
+ * Also be aware that obtaining derived buffers will NOT call {@link #retain()} and so the
+ * reference count will NOT be increased.
  *
  * <h3>Conversion to existing JDK types</h3>
  *
@@ -1191,6 +1194,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
      * Returns a new slice of this buffer's sub-region starting at the current
      * {@code readerIndex} and increases the {@code readerIndex} by the size
      * of the new slice (= {@code length}).
+     * <p>
+     * Also be aware that this method will NOT call {@link #retain()} and so the
+     * reference count will NOT be increased.
      *
      * @param length the size of the new slice
      *
@@ -1661,6 +1667,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
      * identical to {@code buf.slice(buf.readerIndex(), buf.readableBytes())}.
      * This method does not modify {@code readerIndex} or {@code writerIndex} of
      * this buffer.
+     * <p>
+     * Also be aware that this method will NOT call {@link #retain()} and so the
+     * reference count will NOT be increased.
      */
     public abstract ByteBuf slice();
 
@@ -1670,6 +1679,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
      * they maintain separate indexes and marks.
      * This method does not modify {@code readerIndex} or {@code writerIndex} of
      * this buffer.
+     * <p>
+     * Also be aware that this method will NOT call {@link #retain()} and so the
+     * reference count will NOT be increased.
      */
     public abstract ByteBuf slice(int index, int length);
 
@@ -1680,7 +1692,9 @@ public abstract class ByteBuf implements ReferenceCounted, Comparable<ByteBuf> {
      * This method is identical to {@code buf.slice(0, buf.capacity())}.
      * This method does not modify {@code readerIndex} or {@code writerIndex} of
      * this buffer.
-     * The reader and writer marks will not be duplicated.
+     * <p>
+     * The reader and writer marks will not be duplicated. Also be aware that this method will
+     * NOT call {@link #retain()} and so the reference count will NOT be increased.
      */
     public abstract ByteBuf duplicate();