Mercurial > pidgin3 / file diff

--- a/libpurple/dnssrv.h	Fri Jan 31 19:42:12 2014 +0530
+++ b/libpurple/dnssrv.h	Fri Jan 31 20:07:33 2014 +0530
@@ -50,6 +50,8 @@
 typedef void  (*PurpleSrvTxtQueryFailedCallback) (PurpleSrvTxtQueryData *query_data, const gchar *error_message);
 
 /**
+ * PurpleSrvTxtQueryUiOps:
+ *
  * SRV Request UI operations;  UIs should implement this if they want to do SRV
  * lookups themselves, rather than relying on the core.
  *
@@ -64,8 +66,8 @@
 	                    PurpleSrvTxtQueryResolvedCallback resolved_cb,
 	                    PurpleSrvTxtQueryFailedCallback failed_cb);
 
-	/** Called just before @a query_data is freed; this should cancel any
-	 *  further use of @a query_data the UI would make. Unneeded if
+	/** Called just before @query_data is freed; this should cancel any
+	 *  further use of @query_data the UI would make. Unneeded if
 	 *  #resolve is not implemented.
 	 */
 	void (*destroy)(PurpleSrvTxtQueryData *query_data);
@@ -78,6 +80,7 @@
 } PurpleSrvTxtQueryUiOps;
 
 /**
+ * PurpleSrvCallback:
  * @resp: An array of PurpleSrvResponse of size results.  The array
  *        is sorted based on the order described in the DNS SRV RFC.
  *        Users of this API should try each record in resp in order,
@@ -86,18 +89,18 @@
 typedef void (*PurpleSrvCallback)(PurpleSrvResponse *resp, int results, gpointer data);
 
 /**
- * Callback that returns the data retrieved from a DNS TXT lookup.
- *
+ * PurpleTxtCallback:
  * @responses:   A GList of PurpleTxtResponse objects.
  * @data:        The extra data passed to purple_txt_resolve.
+ *
+ * Callback that returns the data retrieved from a DNS TXT lookup.
  */
 typedef void (*PurpleTxtCallback)(GList *responses, gpointer data);
 
 G_BEGIN_DECLS
 
 /**
- * Queries an SRV record.
- *
+ * purple_srv_resolve:
  * @account:   The account that the query is being done for (or NULL)
  * @protocol:  Name of the protocol (e.g. "sip")
  * @transport: Name of the transport ("tcp" or "udp")
@@ -105,6 +108,8 @@
  * @cb:        A callback which will be called with the results
  * @extradata: Extra data to be passed to the callback
  *
+ * Queries an SRV record.
+ *
  * Returns: NULL if there was an error, otherwise return a reference to
  *         a data structure that can be used to cancel the pending
  *         DNS query, if needed.
@@ -112,14 +117,15 @@
 PurpleSrvTxtQueryData *purple_srv_resolve(PurpleAccount *account, const char *protocol, const char *transport, const char *domain, PurpleSrvCallback cb, gpointer extradata);
 
 /**
- * Queries an TXT record.
- *
+ * purple_txt_resolve:
  * @account:   The account that the query is being done for (or NULL)
  * @owner:     Name of the protocol (e.g. "_xmppconnect")
  * @domain:    Domain name to query (e.g. "blubb.com")
  * @cb:        A callback which will be called with the results
  * @extradata: Extra data to be passed to the callback
  *
+ * Queries an TXT record.
+ *
  * Returns: NULL if there was an error, otherwise return a reference to
  *         a data structure that can be used to cancel the pending
  *         DNS query, if needed.
@@ -127,39 +133,45 @@
 PurpleSrvTxtQueryData *purple_txt_resolve(PurpleAccount *account, const char *owner, const char *domain, PurpleTxtCallback cb, gpointer extradata);
 
 /**
- * Get the value of the current TXT record.
+ * purple_txt_response_get_content:
+ * @response:  The TXT response record
  *
- * @response:  The TXT response record
+ * Get the value of the current TXT record.
  *
  * Returns: The value of the current TXT record.
  */
 const gchar *purple_txt_response_get_content(PurpleTxtResponse *response);
 
 /**
- * Destroy a TXT DNS response object.
+ * purple_txt_response_destroy:
+ * @response: The PurpleTxtResponse to destroy.
  *
- * @response: The PurpleTxtResponse to destroy.
+ * Destroy a TXT DNS response object.
  */
 void purple_txt_response_destroy(PurpleTxtResponse *response);
 
 /**
- * Cancel a SRV/TXT query and destroy the associated data structure.
- *
+ * purple_srv_txt_query_destroy:
  * @query_data: The SRV/TXT query to cancel.  This data structure
  *        is freed by this function.
+ *
+ * Cancel a SRV/TXT query and destroy the associated data structure.
  */
 void purple_srv_txt_query_destroy(PurpleSrvTxtQueryData *query_data);
 
 /**
+ * purple_srv_txt_query_set_ui_ops:
+ * @ops: The UI operations structure.
+ *
  * Sets the UI operations structure to be used when doing a SRV/TXT
  * resolve.  The UI operations need only be set if the UI wants to
  * handle the resolve itself; otherwise, leave it as NULL.
- *
- * @ops: The UI operations structure.
  */
 void purple_srv_txt_query_set_ui_ops(PurpleSrvTxtQueryUiOps *ops);
 
 /**
+ * purple_srv_txt_query_get_ui_ops:
+ *
  * Returns the UI operations structure to be used when doing a SRV/TXT
  * resolve.
  *
@@ -168,17 +180,21 @@
 PurpleSrvTxtQueryUiOps *purple_srv_txt_query_get_ui_ops(void);
 
 /**
+ * purple_srv_txt_query_get_query:
+ * @query_data: The SRV/TXT query
+ *
  * Get the query from a PurpleSrvTxtQueryData
  *
- * @query_data: The SRV/TXT query
  * Returns: The query.
  */
 char *purple_srv_txt_query_get_query(PurpleSrvTxtQueryData *query_data);
 
 /**
+ * purple_srv_txt_query_get_type:
+ * @query_data: The query
+ *
  * Get the type from a PurpleSrvTxtQueryData (TXT or SRV)
  *
- * @query_data: The query
  * Returns: The query.
  */
 int purple_srv_txt_query_get_type(PurpleSrvTxtQueryData *query_data);