Bug 26494

Summary:	Misleading deprecation for tp_cli_channel_type_text_call_list_pending_messages
Product:	Telepathy	Reporter:	Cosimo Alfarano <cosimo.alfarano>
Component:	tp-doc	Assignee:	Telepathy bugs list <telepathy-bugs>
Status:	RESOLVED MOVED	QA Contact:	Telepathy bugs list <telepathy-bugs>
Severity:	normal
Priority:	medium
Version:	unspecified
Hardware:	Other
OS:	All
Whiteboard:
i915 platform:		i915 features:

Description Cosimo Alfarano 2010-02-09 08:57:44 UTC

The doc for tp_cli_channel_type_text_call_list_pending_messages (ie http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-channel-text.html)
defines the method as deprecated:

<quote>
tp_cli_channel_type_text_call_list_pending_messages is deprecated and should not be used in newly-written code. Setting this to true is NOT RECOMMENDED for clients that have some sort of persistent message storage - clients SHOULD only acknowledge messages after they have actually stored them, which is impossible if this flag is true
</quote>

While actually only passing b:Clear=True is deprecated (according to TP-specs).

A possible correction would be:

---
passing argument in_Clear=TRUE for tp_cli_channel_type_text_call_list_pending_messages is deprecated and should not be used in newly-written code. Setting this to true is NOT RECOMMENDED for clients that have some sort of persistent message storage - clients SHOULD only acknowledge messages after they have actually stored them, which is impossible if this flag is true
---

Comment 1 Simon McVittie 2010-02-09 09:05:18 UTC

This is tricky to fix in an ideal way, because the docstring is automatically-generated.

A short-term fix would be to make the deprecation-detector in the code generation scripts only match method/tp:deprecated, and not method/arg/tp:deprecated (in pseudo-XPath).

The long-term solution is to make this method unnecessary to call, by having a higher-level API for Text and Messages channels based on some sort of Message object (as seen in telepathy-qt4).

Comment 2 GitLab Migration User 2019-12-03 19:15:46 UTC

-- GitLab Migration Automatic Message --

This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/telepathy/telepathy-doc/issues/2.

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.