DOC: document the listener state transitions

This was done by reading all the code affecting a listener's state,
hopefully it will save some time in the future.
2 files changed