Documentation for TpBaseConnection interfaces_always_present vs. add_interfaces() is lacking
Submitted by Will Thompson @wjt
Assigned to Telepathy bugs list
Description
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.
Version: git master