/soc/2013/ankitkv/gobjectification: 1dde6f706947: Print the enti...
Ankit Vani
a at nevitus.org
Wed Feb 5 13:09:55 EST 2014
Changeset: 1dde6f7069473a8f65b85b137a25bef84f664fc7
Author: Ankit Vani <a at nevitus.org>
Date: 2014-02-05 22:58 +0530
Branch: gtkdoc-conversion
URL: https://hg.pidgin.im/soc/2013/ankitkv/gobjectification/rev/1dde6f706947
Description:
Print the entire PurpleProtocolInfo struct in docs instead of documenting each member.
Seems like a wasted effort, it will be done properly in the .plugins branch.
diffstat:
libpurple/prpl.h | 174 ++++++++++++++++++++++++++++--------------------------
1 files changed, 90 insertions(+), 84 deletions(-)
diffs (truncated from 456 to 300 lines):
diff --git a/libpurple/prpl.h b/libpurple/prpl.h
--- a/libpurple/prpl.h
+++ b/libpurple/prpl.h
@@ -210,11 +210,11 @@ typedef enum /*< flags >*/
*
* Every protocol plugin initializes this structure. It is the gateway
* between purple and the protocol plugin. Many of these callbacks can be
- * NULL. If a callback must be implemented, it has a comment indicating so.
+ * %NULL. If a callback must be implemented, it has a comment indicating so.
*/
struct _PurplePluginProtocolInfo
{
- /**
+ /*
* The size of the PurplePluginProtocolInfo. This should always be sizeof(PurplePluginProtocolInfo).
* This allows adding more functions to this struct without requiring a major version bump.
*/
@@ -235,14 +235,14 @@ struct _PurplePluginProtocolInfo
* functions (e.g. login, send_im etc.) too.
*/
- PurpleProtocolOptions options; /**< Protocol options. */
+ PurpleProtocolOptions options; /* Protocol options. */
- GList *user_splits; /**< A GList of PurpleAccountUserSplit */
- GList *protocol_options; /**< A GList of PurpleAccountOption */
+ GList *user_splits; /* A GList of PurpleAccountUserSplit */
+ GList *protocol_options; /* A GList of PurpleAccountOption */
- PurpleBuddyIconSpec icon_spec; /**< The icon spec. */
+ PurpleBuddyIconSpec icon_spec; /* The icon spec. */
- /**
+ /*
* Returns the base icon name for the given buddy and account.
* If buddy is NULL and the account is non-NULL, it will return the
* name to use for the account's icon. If both are NULL, it will
@@ -252,37 +252,37 @@ struct _PurplePluginProtocolInfo
*/
const char *(*list_icon)(PurpleAccount *account, PurpleBuddy *buddy);
- /**
+ /*
* Fills the four char**'s with string identifiers for "emblems"
* that the UI will interpret and display as relevant
*/
const char *(*list_emblem)(PurpleBuddy *buddy);
- /**
+ /*
* Gets a short string representing this buddy's status. This will
* be shown on the buddy list.
*/
char *(*status_text)(PurpleBuddy *buddy);
- /**
+ /*
* Allows the prpl to add text to a buddy's tooltip.
*/
void (*tooltip_text)(PurpleBuddy *buddy, PurpleNotifyUserInfo *user_info, gboolean full);
- /**
+ /*
* Returns a list of #PurpleStatusType which exist for this account;
* this must be implemented, and must add at least the offline and
* online states.
*/
GList *(*status_types)(PurpleAccount *account);
- /**
+ /*
* Returns a list of #PurpleMenuAction structs, which represent extra
* actions to be shown in (for example) the right-click menu for @node.
*/
GList *(*blist_node_menu)(PurpleBlistNode *node);
- /**
+ /*
* Returns a list of #proto_chat_entry structs, which represent
* information required by the PRPL to join a chat. libpurple will
* call join_chat along with the information filled by the user.
@@ -291,7 +291,7 @@ struct _PurplePluginProtocolInfo
*/
GList *(*chat_info)(PurpleConnection *);
- /**
+ /*
* Returns a hashtable which maps #proto_chat_entry struct identifiers
* to default options as strings based on chat_name. The resulting
* hashtable should be created with g_hash_table_new_full(g_str_hash,
@@ -305,13 +305,13 @@ struct _PurplePluginProtocolInfo
/* All the server-related functions */
- /** This must be implemented. */
+ /* This must be implemented. */
void (*login)(PurpleAccount *);
- /** This must be implemented. */
+ /* This must be implemented. */
void (*close)(PurpleConnection *);
- /**
+ /*
* This PRPL function should return a positive value on success.
* If the message is too big to be sent, return -E2BIG. If
* the account is not connected, return -ENOTCONN. If the
@@ -326,16 +326,16 @@ struct _PurplePluginProtocolInfo
void (*set_info)(PurpleConnection *, const char *info);
- /**
+ /*
* Returns: If this protocol requires the PURPLE_IM_TYPING message to
- * be sent repeatedly to signify that the user is still
- * typing, then the PRPL should return the number of
- * seconds to wait before sending a subsequent notification.
- * Otherwise the PRPL should return 0.
+ * be sent repeatedly to signify that the user is still
+ * typing, then the PRPL should return the number of
+ * seconds to wait before sending a subsequent notification.
+ * Otherwise the PRPL should return 0.
*/
unsigned int (*send_typing)(PurpleConnection *, const char *name, PurpleIMTypingState state);
- /**
+ /*
* Should arrange for purple_notify_userinfo() to be called with
* @who 's user info.
*/
@@ -346,7 +346,7 @@ struct _PurplePluginProtocolInfo
void (*change_passwd)(PurpleConnection *, const char *old_pass,
const char *new_pass);
- /**
+ /*
* Add a buddy to a group on the server.
*
* This PRPL function may be called in situations in which the buddy is
@@ -366,27 +366,27 @@ struct _PurplePluginProtocolInfo
void (*rem_deny)(PurpleConnection *, const char *name);
void (*set_permit_deny)(PurpleConnection *);
- /**
+ /*
* Called when the user requests joining a chat. Should arrange for
* #serv_got_joined_chat to be called.
*
* @components: A hashtable containing information required to
- * join the chat as described by the entries returned
- * by #chat_info. It may also be called when accepting
- * an invitation, in which case this matches the
- * data parameter passed to #serv_got_chat_invite.
+ * join the chat as described by the entries returned
+ * by #chat_info. It may also be called when accepting
+ * an invitation, in which case this matches the
+ * data parameter passed to #serv_got_chat_invite.
*/
void (*join_chat)(PurpleConnection *, GHashTable *components);
- /**
+ /*
* Called when the user refuses a chat invitation.
*
* @components: A hashtable containing information required to
- * join the chat as passed to #serv_got_chat_invite.
+ * join the chat as passed to #serv_got_chat_invite.
*/
void (*reject_chat)(PurpleConnection *, GHashTable *components);
- /**
+ /*
* Returns a chat name based on the information in components. Use
* #chat_info_defaults if you instead need to generate a hashtable
* from a chat name.
@@ -395,24 +395,24 @@ struct _PurplePluginProtocolInfo
*/
char *(*get_chat_name)(GHashTable *components);
- /**
+ /*
* Invite a user to join a chat.
*
* @id: The id of the chat to invite the user to.
* @message: A message displayed to the user when the invitation
- * is received.
+ * is received.
* @who: The name of the user to send the invation to.
*/
void (*chat_invite)(PurpleConnection *, int id,
const char *message, const char *who);
- /**
+ /*
* Called when the user requests leaving a chat.
*
* @id: The id of the chat to leave
*/
void (*chat_leave)(PurpleConnection *, int id);
- /**
+ /*
* Send a whisper to a user in a chat.
*
* @id: The id of the chat.
@@ -422,7 +422,7 @@ struct _PurplePluginProtocolInfo
void (*chat_whisper)(PurpleConnection *, int id,
const char *who, const char *message);
- /**
+ /*
* Send a message to a chat.
* This PRPL function should return a positive value on success.
* If the message is too big to be sent, return -E2BIG. If
@@ -434,38 +434,38 @@ struct _PurplePluginProtocolInfo
* @id: The id of the chat to send the message to.
* @message: The message to send to the chat.
* @flags: A bitwise OR of #PurpleMessageFlags representing
- * message flags.
- * Returns: A positive number or 0 in case of success,
- * a negative error number in case of failure.
+ * message flags.
+ *
+ * Returns: A positive number or 0 in case of success,
+ * a negative error number in case of failure.
*/
int (*chat_send)(PurpleConnection *, int id, const char *message, PurpleMessageFlags flags);
- /** If implemented, this will be called regularly for this prpl's
- * active connections. You'd want to do this if you need to repeatedly
- * send some kind of keepalive packet to the server to avoid being
- * disconnected. ("Regularly" is defined by
- * <literal>KEEPALIVE_INTERVAL</literal> in
- * <filename>libpurple/connection.c</filename>.)
+ /* If implemented, this will be called regularly for this prpl's
+ * active connections. You'd want to do this if you need to repeatedly
+ * send some kind of keepalive packet to the server to avoid being
+ * disconnected. ("Regularly" is defined by
+ * KEEPALIVE_INTERVAL in libpurple/connection.c.)
*/
void (*keepalive)(PurpleConnection *);
- /** new user registration */
+ /* new user registration */
void (*register_user)(PurpleAccount *);
- /**
- * @deprecated Use #PurplePluginProtocolInfo.get_info instead.
+ /*
+ * Deprecated: Use PurplePluginProtocolInfo.get_info instead.
*/
void (*get_cb_info)(PurpleConnection *, int, const char *who);
- /** save/store buddy's alias on server list/roster */
+ /* save/store buddy's alias on server list/roster */
void (*alias_buddy)(PurpleConnection *, const char *who,
const char *alias);
- /** change a buddy's group on a server list/roster */
+ /* change a buddy's group on a server list/roster */
void (*group_buddy)(PurpleConnection *, const char *who,
const char *old_group, const char *new_group);
- /** rename a group on a server list/roster */
+ /* rename a group on a server list/roster */
void (*rename_group)(PurpleConnection *, const char *old_name,
PurpleGroup *group, GList *moved_buddies);
@@ -473,7 +473,7 @@ struct _PurplePluginProtocolInfo
void (*convo_closed)(PurpleConnection *, const char *who);
- /**
+ /*
* Convert the username @who to its canonical form. Also checks for
* validity.
*
@@ -483,13 +483,13 @@ struct _PurplePluginProtocolInfo
* number-based usernames, so function should return NULL in such case.
*
* @account: The account the username is related to. Can
- * be NULL.
+ * be NULL.
* @who: The username to convert.
- * Returns: Normalized username, or NULL, if it's invalid.
+ * Returns: Normalized username, or NULL, if it's invalid.
*/
const char *(*normalize)(const PurpleAccount *account, const char *who);
- /**
+ /*
* Set the buddy icon for the given connection to @img. The prpl
* does NOT own a reference to @img; if it needs one, it must
* #purple_imgstore_ref(@img) itself.
@@ -498,13 +498,14 @@ struct _PurplePluginProtocolInfo
void (*remove_group)(PurpleConnection *gc, PurpleGroup *group);
- /** Gets the real name of a participant in a chat. For example, on
- * XMPP this turns a chat room nick <literal>foo</literal> into
- * <literal>room\@server/foo</literal>
More information about the Commits
mailing list