/dev/masca/gplugin: 3336df05de5b: Add introspection gtkdocs for ...

Changeset: 3336df05de5bf41e8a702f89f6e27cb7d43101b2
Author:	 Jorge Villase?or <[email protected]>
Date:	 2015-03-01 19:08 -0800
Branch:	 soc.2013.gobjectification.plugins
URL: https://hg.pidgin.im/dev/masca/gplugin/rev/3336df05de5b

Description:

Add introspection gtkdocs for server.h
Update the signature of functions on server.c
Add introspection gtk for interfaces neede by server on protocol.h

diffstat:

 libpurple/protocol.h |   15 ++-
 libpurple/server.c   |   16 ++--
 libpurple/server.h   |  186 ++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 189 insertions(+), 28 deletions(-)

diffs (truncated from 303 to 300 lines):

diff --git a/libpurple/protocol.h b/libpurple/protocol.h
--- a/libpurple/protocol.h
+++ b/libpurple/protocol.h
@@ -525,6 +525,11 @@ typedef struct _PurpleProtocolPrivacyIfa
 
 /**
  * PurpleProtocolPrivacyIface:
+ * @add_permit:		Add the buddy on the required authorized list.
+ * @add_deny:		Add the buddy on the required blocked list.
+ * @rem_permit:		Remove the buddy from the requried authorized list.
+ * @rem_deny:		Remove the buddy from the required blocked list.
+ * @set_permit_deny:Update the server with the privacy information on the permit and deny lists.
  *
  * The protocol privacy interface.
  *
@@ -536,15 +541,15 @@ struct _PurpleProtocolPrivacyIface
 	GTypeInterface parent_iface;
 
 	/*< public >*/
-	void (*add_permit)(PurpleConnection *, const char *name);
+	void (*add_permit)(PurpleConnection *gc, const char *name);
 
-	void (*add_deny)(PurpleConnection *, const char *name);
+	void (*add_deny)(PurpleConnection *gc, const char *name);
 
-	void (*rem_permit)(PurpleConnection *, const char *name);
+	void (*rem_permit)(PurpleConnection *gc, const char *name);
 
-	void (*rem_deny)(PurpleConnection *, const char *name);
+	void (*rem_deny)(PurpleConnection *gc, const char *name);
 
-	void (*set_permit_deny)(PurpleConnection *);
+	void (*set_permit_deny)(PurpleConnection *gc);
 };
 
 #define PURPLE_PROTOCOL_HAS_PRIVACY_IFACE(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), PURPLE_TYPE_PROTOCOL_PRIVACY_IFACE))
diff --git a/libpurple/server.c b/libpurple/server.c
--- a/libpurple/server.c
+++ b/libpurple/server.c
@@ -315,24 +315,24 @@ PurpleAttentionType *purple_get_attentio
  * it should be possible.  Probably needs to be done, someday.  Although,
  * the UI for that would be difficult, because groups are Purple-wide.
  */
-void purple_serv_move_buddy(PurpleBuddy *b, PurpleGroup *og, PurpleGroup *ng)
+void purple_serv_move_buddy(PurpleBuddy *buddy, PurpleGroup *orig, PurpleGroup *dest)
 {
 	PurpleAccount *account;
 	PurpleConnection *gc;
 	PurpleProtocol *protocol;
 
-	g_return_if_fail(b != NULL);
-	g_return_if_fail(og != NULL);
-	g_return_if_fail(ng != NULL);
+	g_return_if_fail(buddy != NULL);
+	g_return_if_fail(orig != NULL);
+	g_return_if_fail(dest != NULL);
 
-	account = purple_buddy_get_account(b);
+	account = purple_buddy_get_account(buddy);
 	gc = purple_account_get_connection(account);
 
 	if (gc) {
 		protocol = purple_connection_get_protocol(gc);
-		purple_protocol_server_iface_group_buddy(protocol, gc, purple_buddy_get_name(b),
-				purple_group_get_name(og),
-				purple_group_get_name(ng));
+		purple_protocol_server_iface_group_buddy(protocol, gc, purple_buddy_get_name(buddy),
+				purple_group_get_name(orig),
+				purple_group_get_name(dest));
 	}
 }
 
diff --git a/libpurple/server.h b/libpurple/server.h
--- a/libpurple/server.h
+++ b/libpurple/server.h
@@ -54,8 +54,26 @@ G_BEGIN_DECLS
 /* TODO Could probably move this into the conversation API. */
 unsigned int purple_serv_send_typing(PurpleConnection *gc, const char *name, PurpleIMTypingState state);
 
-void purple_serv_move_buddy(PurpleBuddy *, PurpleGroup *, PurpleGroup *);
-int  purple_serv_send_im(PurpleConnection *, PurpleMessage *msg);
+/**
+ * purple_serv_move_buddy:
+ * @buddy:  The Buddy.
+ * @orig:   Original group.
+ * @dest:   Destiny group.
+ *
+ * Move a buddy from one group to another on server.
+ */
+void purple_serv_move_buddy(PurpleBuddy *buddy, PurpleGroup *orig, PurpleGroup *dest);
+
+/**
+ * purple_serv_send_im:
+ * @gc:     The connection over which to send the typing notification.
+ * @msg:    The message.
+ *
+ * Sends the message to the user through the required protocol.
+ *
+ * Returns: The error value returned from the protocol interface function.
+ */
+int  purple_serv_send_im(PurpleConnection *gc, PurpleMessage *msg);
 
 /**
  * purple_get_attention_type_from_code:
@@ -66,18 +84,138 @@ int  purple_serv_send_im(PurpleConnectio
  */
 PurpleAttentionType *purple_get_attention_type_from_code(PurpleAccount *account, guint type_code);
 
-void purple_serv_get_info(PurpleConnection *, const char *);
-void purple_serv_set_info(PurpleConnection *, const char *);
+/**
+ * purple_serv_get_info:
+ * @gc:     The connection over which to send the typing notification.
+ * @name:   The name of the buddy we were asking information from.
+ *
+ * Request user infromation from the server.
+ */
+void purple_serv_get_info(PurpleConnection *gc, const char *name);
 
-void purple_serv_add_permit(PurpleConnection *, const char *);
-void purple_serv_add_deny(PurpleConnection *, const char *);
-void purple_serv_rem_permit(PurpleConnection *, const char *);
-void purple_serv_rem_deny(PurpleConnection *, const char *);
-void purple_serv_set_permit_deny(PurpleConnection *);
-void purple_serv_chat_invite(PurpleConnection *, int, const char *, const char *);
-void purple_serv_chat_leave(PurpleConnection *, int);
-int  purple_serv_chat_send(PurpleConnection *, int, PurpleMessage *);
-void purple_serv_alias_buddy(PurpleBuddy *);
+/**
+ * purple_serv_set_info:
+ * @gc:     The connection over which to send the typing notification.
+ * @info:   Information text to be sent to the server.
+ *
+ * Set user account information on the server.
+ */
+void purple_serv_set_info(PurpleConnection *gc, const char *info);
+
+/******************************************************************************
+ * Privacy interface
+ *****************************************************************************/
+
+/**
+ * purple_serv_add_permit:
+ * @gc:     The connection over which to send the typing notification.
+ * @name:   The name of the remote user.
+ *
+ * Add the buddy on the required authorized list.
+ */
+void purple_serv_add_permit(PurpleConnection *gc, const char *name);
+
+/**
+ * purple_serv_add_deny:
+ * @gc:     The connection over which to send the typing notification.
+ * @name:   The name of the remote user.
+ *
+ * Add the buddy on the required blocked list.
+ */
+void purple_serv_add_deny(PurpleConnection *gc, const char *name);
+
+/**
+ * purple_serv_rem_permit:
+ * @gc:     The connection over which to send the typing notification.
+ * @name:   The name of the remote user.
+ *
+ * Remove the buddy from the required authorized list.
+ */
+void purple_serv_rem_permit(PurpleConnection *gc, const char *name);
+
+/**
+ * purple_serv_rem_deny:
+ * @gc:     The connection over which to send the typing notification.
+ * @name:   The name of the remote user.
+ *
+ * Remove the buddy from the required blocked list.
+ */
+void purple_serv_rem_deny(PurpleConnection *gc, const char *name);
+
+/**
+ * purple_serv_set_permit_deny:
+ * @gc:     The connection over which to send the typing notification.
+ *
+ * Update the server with the privacy information on the permit and deny lists.
+ */
+void purple_serv_set_permit_deny(PurpleConnection *gc);
+
+/******************************************************************************
+ * Chat Interface
+ *****************************************************************************/
+
+/**
+ * purple_serv_chat_invite
+ * @gc:     The connection over which to send the typing notification.
+ * @id:     The id of the chat to invite the user to.
+ * @message:A message displayed to the user when the invitation.
+ * @name:   The name of the remote user to send the invitation to.
+ *
+ * Invite a user to join a chat.
+ */
+void purple_serv_chat_invite(PurpleConnection *gc, int id, const char *message, const char *name);
+
+/**
+ * purple_serv_chat_leave:
+ * @gc:     The connection over which to send the typing notification.
+ * @id:     The id of the chat to leave.
+ *
+ * Called when the user requests leaving a chat.
+ */
+void purple_serv_chat_leave(PurpleConnection *gc, int id);
+
+/**
+ * purple_serv_chat_send:
+ * @gc:     The connection over which to send the typing notification.
+ * @id:     The id of the chat to send the message to.
+ * @msg:    The message to send to the chat.
+ *
+ * Send a message to a chat.
+ *
+ * This protocol function should return a positive value on
+ * success. If the message is too big to be sent, return
+ * <literal>-E2BIG</literal>. If the account is not connected,
+ * return <literal>-ENOTCONN</literal>. If the protocol is unable
+ * to send the message for another reason, return some other
+ * negative value. You can use one of the valid #errno values, or
+ * just big something.
+ *
+ * Returns:  A positive number or 0 in case of success, a
+ *           negative error number in case of failure.
+ */
+int  purple_serv_chat_send(PurpleConnection *gc, int id, PurpleMessage *msg);
+
+/******************************************************************************
+ * Server Interface
+ *****************************************************************************/
+
+/**
+ * purple_serv_alias_buddy:
+ * @buddy:  The Buddy.
+ *
+ * Save/store buddy's alias on server list/roster
+ */
+void purple_serv_alias_buddy(PurpleBuddy *buddy);
+
+/**
+ * purple_serv_got_alias:
+ * @gc:     The connection over which to send the typing notification.
+ * @who: The name of the buddy whose alias was received.
+ * @alias: The alias that was received.
+ *
+ * Protocol should call this function when it retrieves an alias form the server.
+ *
+ */
 void purple_serv_got_alias(PurpleConnection *gc, const char *who, const char *alias);
 
 /**
@@ -120,6 +258,15 @@ void purple_serv_got_typing(PurpleConnec
  */
 void purple_serv_got_typing_stopped(PurpleConnection *gc, const char *name);
 
+/**
+ * purple_serv_got_im:
+ * @gc:     The connection on which the typing message was received.
+ * @who:    The username of the buddy that sent the message.
+ * @msg:    The actual message received.
+ * @flags:  The flags applicable to this message.
+ *
+ * This function is called by the protocol when it receives an IM message.
+ */
 void purple_serv_got_im(PurpleConnection *gc, const char *who, const char *msg,
 				 PurpleMessageFlags flags, time_t mtime);
 
@@ -128,14 +275,14 @@ void purple_serv_got_im(PurpleConnection
  * @data: The hash function should be g_str_hash() and the equal
  *             function should be g_str_equal().
  */
-void purple_serv_join_chat(PurpleConnection *, GHashTable *data);
+void purple_serv_join_chat(PurpleConnection *gc, GHashTable *data);
 
 /**
  * purple_serv_reject_chat:
  * @data: The hash function should be g_str_hash() and the equal
  *             function should be g_str_equal().
  */
-void purple_serv_reject_chat(PurpleConnection *, GHashTable *data);
+void purple_serv_reject_chat(PurpleConnection *gc, GHashTable *data);
 
 /**
  * purple_serv_got_chat_invite:
@@ -199,6 +346,15 @@ void purple_serv_got_chat_left(PurpleCon
  */
 void purple_serv_got_chat_in(PurpleConnection *g, int id, const char *who,
 					  PurpleMessageFlags flags, const char *message, time_t mtime);
+
+/**
+ * purple_serv_send_file:
+ * @g:      The connection on which the message was received.
+ * @who:    The name of the user to who send the file.
+ * @file:   The filename to send.
+ *
+ * Send a filename to a given contact.
+ */