[Bug 33406] New: Documentation for TpBaseConnection interfaces_always_present vs. add_interfaces() is lacking

[bugzilla-daemon at freedesktop.org]

https://bugs.freedesktop.org/show_bug.cgi?id=33406

           Summary: Documentation for TpBaseConnection
                    interfaces_always_present vs. add_interfaces() is
                    lacking
           Product: Telepathy
           Version: git master
          Platform: Other
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: medium
         Component: tp-glib
        AssignedTo: telepathy-bugs at lists.freedesktop.org
        ReportedBy: will.thompson at collabora.co.uk
         QAContact: telepathy-bugs at lists.freedesktop.org


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.

-- 
Configure bugmail: https://bugs.freedesktop.org/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.
You are the assignee for the bug.