documented decoder pitfalls

to avoid mistakes found in https://github.com/netty/netty/issues/3184