Rocumented decoder pitfalls to avoid mistakes found in [#3184]

codec/src/main/java/io/netty/handler/codec/ByteToMessageDecoder.java

@@ -41,8 +41,29 @@ import java.util.List;
  *     }
  * </pre>
  *
+ * <h3>Frame detection</h3>
+ * <p>
+ * Generally frame detection should be handled earlier in the pipeline by adding a
+ * {@link DelimiterBasedFrameDecoder}, {@link FixedLengthFrameDecoder}, {@link LengthFieldBasedFrameDecoder},
+ * or {@link LineBasedFrameDecoder}.
+ * <p>
+ * If a custom frame decoder is required, then one needs to be careful when implementing
+ * one with {@link ByteToMessageDecoder}. Ensure there are enough bytes in the buffer for a
+ * complete frame by checking {@link ByteBuf#readableBytes()}. If there are not enough bytes
+ * for a complete frame, return without modify the reader index to allow more bytes to arrive.
+ * <p>
+ * To check for complete frames without modify the reader index, use methods like {@link ByteBuf#getInt(int)}.
+ * One <strong>MUST</strong> use the reader index when using methods like {@link ByteBuf#getInt(int)}.
+ * For example calling <tt>in.getInt(0)</tt> is assuming the frame starts at the beginning of the buffer, which
+ * is not always the case. Use <tt>in.getInt(in.readerIndex())</tt> instead.
+ * <h3>Pitfalls</h3>
+ * <p>
  * Be aware that sub-classes of {@link ByteToMessageDecoder} <strong>MUST NOT</strong>
  * annotated with {@link @Sharable}.
+ * <p>
+ * Some methods such as {@link ByteBuf.readBytes(int)} will cause a memory leak if the returned buffer
+ * is not released or added to the <tt>out</tt> {@link List}. Use derived buffers like {@link ByteBuf.readSlice(int)}
+ * to avoid leaking memory.
  */
 public abstract class ByteToMessageDecoder extends ChannelInboundHandlerAdapter {