documented decoder pitfalls

to avoid mistakes found in https://github.com/netty/netty/issues/3184
Hmm, okay maybe I need to be more clear.  Yes you can modify the readerIndex, but it is generally a bug to do so when you are not decoding any messages.  For example the naive approach to implement a 4 byte length field (without using `LengthFieldBasedFrameDecoder`) would look like:
```
public void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) {
    int length = in.readInt();  // this is a bug and will cause the subsequent decode to be missing the length field
    if (in.readableBytes() < length) {
        return;
    }
    ...
}
```
where as the correct implementation is:
```
public void decode(ChannelHandlerContext ctx, ByteBuf in, List<Object> out) {
    int length = in.getInt(in.readerIndex());
    if (in.readableBytes() < length) {
        return;
    }
    in.skipBytes(4);
    ...
}
```