28682 events docs

@gadamc @tomblench Could you take a read of the documentation and tests to check they make sense and are consistent with each other? I think they are.