event: add some docs and improve the channel handling