I read the preamble for this class and was really terrified.
Check out http://cgit.collabora.co.uk/git/user/wjt/telepathy-glib.git/commit/?h=base-contact-list-clarifications&id=eedfef38686cc922f2104bd4a1bae8ff5575a598
This is good, except it does look as if you tailed off towards the end. Examples and lists are pretty, and certainly better than a wall of text. If you can be bothered it'd be nice to do the same for the "To support user-defined contact groups too ..." text.
But this is totally an improvement.
Merged to 0.14 and master. Ta.