I just explained the distinction between TpBaseConnectionClass.interfaces_always_present and tp_base_connection_add_interfaces() to a CM author. The documentation for these two is technically correct, but doesn't do a very good job of explaining the point of the two ways to add interfaces (and how they're different to G_IMPLEMENT_INTERFACE()).

Quoth me on the IRC:

<wjt> so the distinction is:
<wjt> * if every connection will *actually* support (say) avatars, that interface should be in the interfaces_always_present list
<wjt> * if it might not, and you can only tell once you're connected, you need to call tp_base_connection_add_interfaces when you discover that it is supported
<wjt> i'll find an example in Gabble.
<wjt> here <http://git.collabora.co.uk/?p=telepathy-gabble.git;a=blob;f=src/connection.c;h=4a4750cb71117d43e4358face865460fcff3f5c2;hb=HEAD#l893> the interfaces_always_present field is set to the value defined here: <http://git.collabora.co.uk/?p=telepathy-gabble.git;a=blob;f=src/connection.c;h=4a4750cb71117d43e4358face865460fcff3f5c2;hb=HEAD#l773>
<wjt> but you can see that there are a few interfaces (like Mail Notification) which not all XMPP connections support
<wjt> so in this internal function <http://git.collabora.co.uk/?p=telepathy-gabble.git;a=blob;f=src/connection.c;h=4a4750cb71117d43e4358face865460fcff3f5c2;hb=HEAD#l2628>, called after we've connected to the XMPP server and checked what features it supports, the extra interfaces are added by calling tp_base_connection_add_interfaces()

I think including an example of this distinction—and, more generally, what subclasses are expected to implement/override—in the introduction to the TpBaseConnection documentation would be helpful.