Attachment 88003 Details for Bug 70731 – [WiP] Add more pseudo-doc-comments to teach g-i about TpBaseProtocol

[patch] [WiP] Add more pseudo-doc-comments to teach g-i about TpBaseProtocol

0014-Add-more-pseudo-doc-comments-to-teach-g-i-about-TpBa.patch (text/plain), 7.80 KB, created by Simon McVittie on 2013-10-22 15:17:22 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2013-10-22 15:17:22 UTC

Size: 7.80 KB

patch

obsolete

>From cd165e8e0f739db2326773ca3fe39056d3832d47 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>Date: Mon, 21 Oct 2013 19:27:18 +0100
>Subject: [PATCH 14/16] Add more pseudo-doc-comments to teach g-i about
> TpBaseProtocol
>
>---
> telepathy-glib/base-protocol.c | 159 ++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 157 insertions(+), 2 deletions(-)
>
>diff --git a/telepathy-glib/base-protocol.c b/telepathy-glib/base-protocol.c
>index aa70d50..bc460a1 100644
>--- a/telepathy-glib/base-protocol.c
>+++ b/telepathy-glib/base-protocol.c
>@@ -294,6 +294,23 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
>  */
> 
> /**
>+ * TpBaseProtocolClass::get_parameters:
>+ * @self: a protocol
>+ *
>+ * Virtual method to get the allowed parameters for connections
>+ * to a protocol.
>+ *
>+ * Returns the parameters supported by this protocol, as an array of structs
>+ * which must remain valid at least as long as @self exists (it will typically
>+ * be a global static array).
>+ *
>+ * Returns: (transfer none) (array zero-terminated=1): a description of the
>+ *  parameters supported by this protocol
>+ *
>+ * Since: 0.11.11
>+ */
>+
>+/**
>  * TpBaseProtocolNewConnectionFunc:
>  * @self: a protocol
>  * @asv: (transfer none) (element-type utf8 GObject.Value): the parameters
>@@ -313,6 +330,24 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
>  */
> 
> /**
>+ * TpBaseProtocolClass::new_connection:
>+ * @self: a protocol
>+ * @asv: (transfer none) (element-type utf8 GObject.Value): the parameters
>+ *  provided via D-Bus
>+ * @error: used to return an error if %NULL is returned
>+ *
>+ * Create a new connection to this protocol.
>+ * This is used to implement the RequestConnection D-Bus method.
>+ *
>+ * Implementations of #TpBaseProtocolClass.new_connection may assume that
>+ * the parameters in @asv conform to the specifications given by
>+ * #TpBaseProtocolClass.get_parameters.
>+ *
>+ * Returns: (transfer full): a new connection, or %NULL on error
>+ * Since: 0.11.11
>+ */
>+
>+/**
>  * TpBaseProtocolNormalizeContactFunc:
>  * @self: a protocol
>  * @contact: a contact's identifier
>@@ -328,6 +363,21 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
>  */
> 
> /**
>+ * TpBaseProtocol::normalize_contact:
>+ * @self: a protocol
>+ * @contact: a contact's identifier
>+ * @error: used to return an error if %NULL is returned
>+ *
>+ * Perform best-effort offline normalization
>+ * of a contact's identifier: either return a newly allocated string
>+ * that is the normalized form of @contact, or raise an error and return %NULL.
>+ *
>+ * Returns: (transfer full): a normalized identifier, or %NULL on error
>+ *
>+ * Since: 0.11.11
>+ */
>+
>+/**
>  * TpBaseProtocolIdentifyAccountFunc:
>  * @self: a protocol
>  * @asv: parameters that might be passed to the RequestConnection D-Bus method
>@@ -348,6 +398,26 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
>  */
> 
> /**
>+ * TpBaseProtocol::identify_account:
>+ * @self: a protocol
>+ * @asv: parameters that might be passed to the RequestConnection D-Bus method
>+ * @error: used to return an error if %NULL is returned
>+ *
>+ * Choose a unique name for an account whose
>+ * connection parameters are @asv. This will typically return a copy of
>+ * the 'account' parameter from @asv, but may do something more complex (for
>+ * instance, on IRC it could combine the nickname and the IRC network).
>+ *
>+ * Implementations of #TpBaseProtocolClass.identify_account may assume that
>+ * the parameters in @asv conform to the specifications given by
>+ * #TpBaseProtocolClass.get_parameters.
>+ *
>+ * Returns: (transfer full): a unique name for the account, or %NULL on error
>+ *
>+ * Since: 0.11.11
>+ */
>+
>+/**
>  * TpBaseProtocolGetInterfacesFunc:
>  * @self: a protocol
>  *
>@@ -388,6 +458,41 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
>  */
> 
> /**
>+ * TpBaseProtocol::get_connection_details:
>+ * @self: a protocol
>+ * @connection_interfaces: (out) (transfer full): used to return a
>+ *  %NULL-terminated array of interfaces which might be implemented on
>+ *  connections to this protocol
>+ * @channel_manager_types: (out) (transfer full) (array zero-terminated=1):
>+ *  used to return a %G_TYPE_INVALID-terminated array of types that implement
>+ *  #TpChannelManager, which must include all channel managers that might be
>+ *  present on connections to this protocol; the channel managers should
>+ *  all implement #TpChannelManagerIface.type_foreach_channel_class. The
>+ *  array will be freed with g_free() by the caller.
>+ * @icon_name: (out) (transfer full): used to return the name of an icon
>+ *  for this protocol, such as "im-icq", or an empty string
>+ * @english_name: (out) (transfer full): used to return a human-readable
>+ *  but non-localized name for this protocol, or an empty string
>+ * @vcard_field: (out) (transfer full): used to return the name of the vCard
>+ *  field typically used with this protocol, or an empty string
>+ *
>+ * Virtual method to get the D-Bus interfaces implemented by
>+ * @self, in addition to the Protocol interface.
>+ *
>+ * Since: 0.11.11
>+ */
>+
>+/**
>+ * TpBaseProtocol::get_statuses:
>+ * @self: a protocol
>+ *
>+ * Return the presence statuses supported by this protocol.
>+ *
>+ * Returns: (transfer none) (array zero-terminated=1): the statuses
>+ * Since: 0.13.7
>+ */
>+
>+/**
>  * TpBaseProtocolGetAvatarDetailsFunc:
>  * @self: a protocol
>  * @supported_mime_types: (out) (transfer full): used to return a
>@@ -414,6 +519,44 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
>  */
> 
> /**
>+ * TpBaseProtocol::get_avatar_details:
>+ * @self: a protocol
>+ * @supported_mime_types: (out) (transfer full): used to return a
>+ *  %NULL-terminated array of supported avatar mime types
>+ * @min_height: (out): used to return the minimum height in pixels of an
>+ *  avatar on this protocol, which may be 0
>+ * @min_width: (out): used to return the minimum width in pixels of an avatar
>+ *  on this protocol, which may be 0
>+ * @rec_height: (out): used to return the rec height in pixels
>+ *  of an avatar on this protocol, or 0 if there is no preferred height
>+ * @rec_width: (out): used to return the rec width in pixels
>+ *  of an avatar on this protocol, or 0 if there is no preferred width
>+ * @max_height: (out): used to return the maximum height in pixels of an
>+ *  avatar on this protocol, or 0 if there is no limit
>+ * @max_width: (out): used to return the maximum width in pixels of an avatar
>+ *  on this protocol, or 0 if there is no limit
>+ * @max_bytes: (out): used to return the maximum size in bytes of an avatar on
>+ *  this protocol, or 0 if there is no limit
>+ *
>+ * Get the supported avatar details for the protocol implemented by @self.
>+ *
>+ * Since: 0.13.7
>+ */
>+
>+/**
>+ * TpBaseProtocol::dup_authentication_types:
>+ * @self: a protocol
>+ *
>+ * Return an array of channel types and/or interfaces indicating the
>+ * channels that can appear before a connection to this protocol will
>+ * finish connecting.
>+ *
>+ * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): the
>+ *  authentication channel types as D-Bus interface names
>+ * Since: 0.13.7
>+ */
>+
>+/**
>  * TpBaseProtocolGetInterfacesArrayFunc:
>  * @self: a #TpBaseProtocol
>  *
>@@ -438,8 +581,20 @@ tp_cm_param_filter_string_nonempty (const TpCMParamSpec *paramspec,
>  * }
>  * ]|
>  *
>- * Returns: (transfer container): a #GPtrArray of static strings for D-Bus
>- *   interfaces implemented by this client.
>+ * Returns: (transfer container) (element-type utf8): a #GPtrArray of
>+ *  static strings for D-Bus interfaces implemented by this client.
>+ *
>+ * Since: 0.19.4
>+ */
>+
>+/**
>+ * TpBaseProtocol::get_interfaces_array:
>+ * @self: a #TpBaseProtocol
>+ *
>+ * Return the extra interfaces implemented by this protocol.
>+ *
>+ * Returns: (transfer container) (element-type utf8): a #GPtrArray of
>+ *  static strings for D-Bus interfaces implemented by this protocol.
>  *
>  * Since: 0.19.4
>  */
>-- 
>1.8.4.rc3
>

Actions: View | Splinter Review

Attachments on bug 70731: 87997 | 87998 | 87999 | 88000 | 88001 | 88002 | 88003 | 88004 | 88005

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.