[Telepathy] "contact #2 in the GetContactAttributes result has no contact-id"

[Murray Cumming]

On Mon, 2009-01-05 at 10:12 +0000, Will Thompson wrote:
> Murray Cumming wrote:
> > On Tue, 2008-12-23 at 16:06 +0000, Will Thompson wrote:
> >   
> >> (Incidentally, list_contacts/main.c contains the following:
> >>
> >>   tp_cli_connection_call_disconnect (connection, -1, NULL, NULL,
> >>     NULL, NULL); /* Also destroys the connection object. */
> >>   connection = NULL;
> >>
> >> Calling _disconnect on the TpConnection proxy object doesn't destroy it.
> >> Connection objects on the bus (are supposed to) go away shortly after
> >> they move to state Disconnected, but clients still need to free up their
> >> proxy objects.)**
> >>     
> >
> > Then this text in the documentation is misleading:
> > http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-connection.html#tp-cli-connection-call-disconnect
> > "Request that the connection be closed. This closes the connection if
> > it's not already in DISCONNECTED state, and destroys the connection
> > object."
> >
> > Does that mean that just the server side connection object is destroyed
> > (effectively invalidating the local TpConnection proxy for it, which
> > should then be destroyed manually)?
> >   
> 
> Yes. It's the documentation of the Disconnect() D-Bus method, taken
> directly from the spec, as is all the documentation of tp_cli_* methods.
> 
> Perhaps all such methods should be documented as something like:
> 
>     Calls the Foo() method on D-Bus interface Bar, which the
>     specification defines as follows:
> 
>     [Docs from spec]
> 
> Would that make it clearer?

Yes, slightly. But I don't think the D-Bus API spec documentation should
ever be inserted into the telepathy-glib gtk-doc documentation even with
that caveat. I'd rather see instead:
a) a simple direct link to the relevant part of the the D-Bus API spec.
and
b) Hand-written documentation that actually documents that C API.

-- 
murrayc at murrayc.com
www.murrayc.com
www.openismus.com