AuthHandler: add a bit of documentation.

2 files changed, 69 insertions, 9 deletions

diff --git a/wocky/wocky-auth-handler.c b/wocky/wocky-auth-handler.c
index 37e0b38..d1d3daf 100644
--- a/wocky/wocky-auth-handler.c
+++ b/wocky/wocky-auth-handler.c
@@ -32,18 +32,50 @@ wocky_auth_handler_get_type (void)
   return g_define_type_id__volatile;
 }
 
+/**
+ * wocky_auth_handler_get_mechanism:
+ * @handler: a handler for a SASL mechanism.
+ *
+ * Returns the name of the SASL mechanism @handler implements.
+ *
+ * Returns: the name of the SASL mechanism @handler implements.
+ */
 const gchar *
 wocky_auth_handler_get_mechanism (WockyAuthHandler *handler)
 {
   return WOCKY_AUTH_HANDLER_GET_IFACE (handler)->mechanism;
 }
 
+/**
+ * wocky_auth_handler_is_plain:
+ * @handler: a handler for a SASL mechanism.
+ *
+ * Checks whether @handler sends secrets in plaintext. This may be used to
+ * decide whether to use @handler on an insecure XMPP connection.
+ *
+ * Returns: %TRUE if @handler sends secrets in plaintext.
+ */
 gboolean
 wocky_auth_handler_is_plain (WockyAuthHandler *handler)
 {
   return WOCKY_AUTH_HANDLER_GET_IFACE (handler)->plain;
 }
 
+/**
+ * wocky_auth_handler_get_initial_response:
+ * @handler: a handler for a SASL mechanism
+ * @initial_data: (out) (transfer full): initial data to send to the server, if
+ *  any
+ * @error: an optional location for a #GError to fill, or %NULL
+ *
+ * Called when authentication begins to fetch the initial data to send to the
+ * server in the <code>&lt;auth/&gt;</code> stanza.
+ *
+ * If this function returns %TRUE, @initial_data will be non-%NULL if @handler
+ * provides an initial response, and %NULL otherwise.
+ *
+ * Returns: %TRUE on success; %FALSE otherwise.
+ */
 gboolean
 wocky_auth_handler_get_initial_response (WockyAuthHandler *handler,
     GString **initial_data,
@@ -61,6 +93,20 @@ wocky_auth_handler_get_initial_response (WockyAuthHandler *handler,
   return func (handler, initial_data, error);
 }
 
+/**
+ * wocky_auth_handler_handle_auth_data:
+ * @handler: a #WockyAuthHandler object
+ * @data: the challenge string
+ * @response: (out) (transfer full): a location to fill with a challenge
+ *  response in a #GString
+ * @error: an optional location for a #GError to fill, or %NULL
+ *
+ * Asks @handler to respond to a <code>&lt;challenge/&gt;</code> stanza or a
+ * <code>&lt;success/&gt;</code> with data. On success, @handler will put
+ * response data into @response, Base64-encoding it if appropriate.
+ *
+ * Returns: %TRUE on success, otherwise %FALSE
+ */
 gboolean
 wocky_auth_handler_handle_auth_data (
     WockyAuthHandler *handler,
@@ -85,6 +131,19 @@ wocky_auth_handler_handle_auth_data (
   return func (handler, data, response, error);
 }
 
+/**
+ * wocky_auth_handler_handle_success:
+ * @handler: a #WockyAuthHandler object
+ * @error: an optional location for a #GError to fill, or %NULL
+ *
+ * Called when a <code>&lt;success/&gt;</code> stanza is received
+ * during authentication. If no error is returned, then authentication
+ * is considered finished. (Typically, an error is only raised if the
+ * <code>&lt;success/&gt;</code> stanza was received earlier than
+ * expected)
+ *
+ * Returns: %TRUE on success, otherwise %FALSE
+ */
 gboolean
 wocky_auth_handler_handle_success (
     WockyAuthHandler *handler,
diff --git a/wocky/wocky-auth-handler.h b/wocky/wocky-auth-handler.h
index 448558c..dfef4f9 100644
--- a/wocky/wocky-auth-handler.h
+++ b/wocky/wocky-auth-handler.h
@@ -21,7 +21,7 @@ typedef struct _WockyAuthHandler WockyAuthHandler;
 /**
  * WockyAuthInitialResponseFunc:
  * @handler: a #WockyAuthHandler object
- * @initial_data: a #GString location to fill with the initial data, or %NULL to ignre
+ * @initial_data: (out): a #GString location to fill with the initial data
  * @error: an optional location for a #GError to fill, or %NULL
  *
  * Called when authentication begins, if the mechanism allows a
@@ -29,10 +29,10 @@ typedef struct _WockyAuthHandler WockyAuthHandler;
  * XMPP, corresponds to sending the <code>&lt;auth/&gt;</code> stanza
  * to the server).
  *
- * The function should return %TRUE on success and optionally set the
- * @initial_data to a string (allocated using g_malloc()) if there is
- * initial data to send. On error it should return %FALSE and set the
- * error
+ * The function should return %TRUE on success, and optionally set the
+ * @initial_data to a string if there is
+ * initial data to send. On error, it should return %FALSE and set
+ * @error.
  *
  * Returns: %TRUE on success, otherwise %FALSE
  **/
@@ -43,14 +43,15 @@ typedef gboolean (*WockyAuthInitialResponseFunc) (WockyAuthHandler *handler,
 /**
  * WockyAuthChallengeFunc:
  * @handler: a #WockyAuthHandler object
- * @data: the challange string
- * @response: a location to fill with a challenge response in a #GString
+ * @data: the challenge string
+ * @response: (out) (transfer full): a location to fill with a challenge
+ *  response in a #GString
  * @error: an optional location for a #GError to fill, or %NULL
  *
- * Called During authentication, when a
+ * Called during authentication when a
  * <code>&lt;challenge/&gt;</code> stanza or a
  * <code>&lt;success/&gt;</code> with data is received. The handler
- * should put response data in response (allocate using g_malloc()) if
+ * should put response data into @response if
  * appropriate. The handler is responsible for Base64-encoding
  * responses if appropriate.
  *