[Bug 24061] TpAccount, TpAccountManager: add convenience API similar to libempathy's

[bugzilla-daemon at freedesktop.org]

http://bugs.freedesktop.org/show_bug.cgi?id=24061





--- Comment #22 from Jonny Lamb <jonny.lamb at collabora.co.uk>  2009-09-25 14:12:07 PST ---
(In reply to comment #14)
> It's worth documenting which properties the notify signal works on (or perhaps
> documenting, once, that the notify signal works on all properties, if that
> turns out to be true).

Done.

> Each property/getter pair should be cross-referenced in at least one direction
> (I usually find it looks nicer to document the property properly, and document
> the getter as "Returns: the value of the TpAccount::teapot property").

Done.

> Each property, or each getter, or both should document which feature needs to
> be enabled: perhaps something like
> 
>     This is not guaranteed to have been retrieved until
> tp_account_prepare_async has finished; until then, the value is ""
> 
> for core, and
> 
>     This is not guaranteed to have been retrieved until
> tp_account_prepare_async has finished for the feature
> TP_ACCOUNT_FEATURE_TEAPOTS; until then, the value is TP_TEAPOT_NONE
> 
> in future for non-core?
> 
> (This is one advantage that the "ready" terminology had - you could say "until
> FeatureTeapots is ready" and it didn't sound awkward)

Done.

> > 2295  * Gets the value of the Nickname parameter on @account.
> 
> Nitpicking: please call properties properties, not parameters, here and
> elsewhere. Only the Parameters property contains parameters.

Ah yes, I frequently got confused between parameters and properties.

> > 165  * TP_ACCOUNT_FEATURE_CORE:
> 
> This should explain briefly what preparing this feature means: in this case,
> something like "the basic properties of the Account have been retrieved and are
> available for use, and change-notification has been set up".

Done.

> > 174  * tp_account_get_feature_quark_core:
> 
> I don't think this should be documented, assuming people are meant to access it
> through the TP_ACCOUNT_FEATURE_CORE macro. It can go in a <SUBSECTION Private>
> if that's the case. (See also: the GType macros.)

Ah okay, done.

> > 1419  * Set the connection of the account by specifying the connection object path.
> > 1420  * This function does not return a new ref and it is not guaranteed that the
> > 1421  * returned #TpConnection object is ready.
> 
> It would be good if the docstring explained why you'd ever want to call this
> method... presumably it's intended to be used when you already know the object
> path, from a HandleChannels call or something?

Done.

> > 1218    * TpAccount:nickname
> > 1220    * The account's nickname.
> 
> This sounds easy to confuse with DisplayName. "The nickname that should be set
> for the user on this account" would be less ambiguous.

Done.

> > 1082           "DisplayName",
> > 1083           "The accounts display name",
> 
> Nitpicking: apostrophes are recommended :-) There are various other instances
> of what is presumably en_BE from Empathy in the property descriptions.

Done.

> All the getters should ideally have a g_return_val_if_fail (TP_IS_ACCOUNT
> (self), .)) guard, although I don't think that's a merge blocker.

Done.


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