Add documentation for libstun and fix some docs elsewhere

6 files changed, 605 insertions, 57 deletions

diff --git a/stun/stunagent.h b/stun/stunagent.h
index 4f02f4d..d47b171 100644
--- a/stun/stunagent.h
+++ b/stun/stunagent.h
@@ -60,10 +60,28 @@
 
 #include <sys/types.h>
 
+/**
+ * StunAgent:
+ *
+ * An opaque structure representing the STUN agent.
+ */
 typedef struct stun_agent_t StunAgent;
 
 #include "stunmessage.h"
 
+/**
+ * StunCompatibility:
+ * @STUN_COMPATIBILITY_RFC3489: Use the STUN specifications compatible with
+ * RFC 3489
+ * @STUN_COMPATIBILITY_RFC5389: Use the STUN specifications compatible with
+ * RFC 5389
+ * @STUN_COMPATIBILITY_WLM2009: Use the STUN specifications compatible with
+ * Windows Live Messenger 2009 (a mix between RFC3489 and RFC5389, as well as
+ * a special usecase against a typo in their code)
+ * @STUN_COMPATIBILITY_LAST: Dummy last compatibility mode
+ *
+ * Enum that specifies the STUN compatibility mode of the #StunAgent
+ */
 typedef enum {
   STUN_COMPATIBILITY_RFC3489,
   STUN_COMPATIBILITY_RFC5389,
@@ -72,31 +90,40 @@ typedef enum {
 } StunCompatibility;
 
 
+/**
+ * StunValidationStatus:
+ * @STUN_VALIDATION_SUCCESS: The message is validated
+ * @STUN_VALIDATION_NOT_STUN: This is not a valid STUN message
+ * @STUN_VALIDATION_INCOMPLETE_STUN: The message seems to be valid but incomplete
+ * @STUN_VALIDATION_BAD_REQUEST: The message does not have the cookie or the
+ * fingerprint while the agent needs it with its usage
+ * @STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST: The message is valid but
+ * unauthorized with no username and message-integrity attributes.
+ * A BAD_REQUEST error must be generated
+ * @STUN_VALIDATION_UNAUTHORIZED: The message is valid but unauthorized as
+ * the username/password do not match.
+ * An UNAUTHORIZED error must be generated
+ * @STUN_VALIDATION_UNMATCHED_RESPONSE: The message is valid but this is a
+ * response/error that doesn't match a previously sent request
+ * @STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE: The message is valid but
+ * contains one or more unknown comprehension attributes.
+ * stun_agent_build_unknown_attributes_error() should be called
+ * @STUN_VALIDATION_UNKNOWN_ATTRIBUTE: The message is valid but contains one
+ * or more unknown comprehension attributes. This is a response, or error,
+ * or indication message and no error response should be sent
+ *
+ * This enum is used as the return value of stun_agent_validate() and represents
+ * the status result of the validation of a STUN message.
+ */
 typedef enum {
-  /* The message is validated */
   STUN_VALIDATION_SUCCESS,
-  /* This is not a valid STUN message */
   STUN_VALIDATION_NOT_STUN,
-  /* The message seems to be valid but incomplete */
   STUN_VALIDATION_INCOMPLETE_STUN,
-  /* The message does not have the cookie or the fingerprint
-   * while the agent needs it with its usage */
   STUN_VALIDATION_BAD_REQUEST,
-  /* The message is valid but unauthorized with no username and message-integrity
-     attributes. A BAD_REQUEST error must be generated */
   STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST,
-  /* The message is valid but unauthorized as the username/password do not match.
-     An UNAUTHORIZED error must be generated */
   STUN_VALIDATION_UNAUTHORIZED,
-  /* The message is valid but this is a response/error that doesn't match
-   * a previously sent request */
   STUN_VALIDATION_UNMATCHED_RESPONSE,
-  /* The message is valid but contains one or more unknown comprehension
-   * attributes. stun_agent_build_unknown_attributes_error should be called */
   STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE,
-  /* The message is valid but contains one or more unknown comprehension
-   * attributes. This is a response, or error, or indication message
-   * and no error response should be sent */
   STUN_VALIDATION_UNKNOWN_ATTRIBUTE,
 } StunValidationStatus;
 
@@ -157,39 +184,251 @@ struct stun_agent_t {
   StunAgentUsageFlags usage_flags;
 };
 
+/**
+ * StunDefaultValidaterData:
+ * @username: The username
+ * @username_len: The length of the @username
+ * @password: The password
+ * @password_len: The length of the @password
+ *
+ * This structure is used as an element of the user_data to the
+ * stun_agent_default_validater() function for authenticating a STUN
+ * message during validationg.
+ * <para> See also: stun_agent_default_validater() </para>
+ */
 typedef struct {
   uint8_t *username;
   size_t username_len;
   uint8_t *password;
   size_t password_len;
-} stun_validater_data;
+} StunDefaultValidaterData;
 
 
+/**
+ * StunMessageIntegrityValidate:
+ * @agent: The #StunAgent
+ * @message: The #StunMessage being validated
+ * @username: The username found in the @message
+ * @username_len: The length of @username
+ * @password: The password associated with that username. This argument is a
+ * pointer to a byte array that must be set by the validater function.
+ * @password_len: The length of @password which must also be set by the
+ * validater function.
+ * @user_data: Data to give the function
+ *
+ * This is the prototype for the @validater argument of the stun_agent_validate()
+ * function.
+ * <para> See also: stun_agent_validate() </para>
+ * Returns: %TRUE if the authentication was successful,
+ * %FALSE if the authentication failed
+ */
 typedef bool (*StunMessageIntegrityValidate) (StunAgent *agent,
     StunMessage *message, uint8_t *username, uint16_t username_len,
     uint8_t **password, size_t *password_len, void *user_data);
 
+/**
+ * stun_agent_default_validater:
+ * @agent: The #StunAgent
+ * @message: The #StunMessage being validated
+ * @username: The username found in the @message
+ * @username_len: The length of @username
+ * @password: The password associated with that username. This argument is a
+ * pointer to a byte array that must be set by the validater function.
+ * @password_len: The length of @password which must also be set by the
+ * validater function.
+ * @user_data: This must be an array of #StunDefaultValidaterData structures.
+ * The last element in the array must have a username set to NULL
+ *
+ * This is a helper function to be used with stun_agent_validate(). If no
+ * complicated processing of the username needs to be done, this function can
+ * be used with stun_agent_validate() to quickly and easily match the username
+ * of a STUN message with its password. Its @user_data argument must be an array
+ * of #StunDefaultValidaterData which will allow us to map a username to a
+ * password
+ * <para> See also: stun_agent_validate() </para>
+ * Returns: %TRUE if the authentication was successful,
+ * %FALSE if the authentication failed
+ */
 bool stun_agent_default_validater (StunAgent *agent,
     StunMessage *message, uint8_t *username, uint16_t username_len,
     uint8_t **password, size_t *password_len, void *user_data);
 
+/**
+ * stun_agent_init:
+ * @agent: The #StunAgent to initialize
+ * @known_attributes: An array of #uint16_t specifying which attributes should
+ * be known by the agent. Any STUN message received that contains a mandatory
+ * attribute that is not in this array will yield a
+ * #STUN_VALIDATION_UNKNOWN_REQUEST_ATTRIBUTE or a
+ * #STUN_VALIDATION_UNKNOWN_ATTRIBUTE error when calling stun_agent_validate()
+ * @compatibility: The #StunCompatibility to use for this agent. This will affect
+ * how the agent builds and validates the STUN messages
+ * @usage_flags: A bitflag using #StunAgentUsageFlags values to define which
+ * STUN usages the agent should use.
+ *
+ * This function must be called to initialize an agent before it is being used.
+ *
+ <note>
+   <para>
+    The @known_attributes data must exist in memory as long as the @agent is used
+    </para>
+    <para>
+    If the #STUN_AGENT_USAGE_SHORT_TERM_CREDENTIALS and
+    #STUN_AGENT_USAGE_LONG_TERM_CREDENTIALS usage flags are not set, then the
+    agent will default in using the short term credentials mechanism
+    </para>
+    <para>
+    The #STUN_AGENT_USAGE_USE_FINGERPRINT and #STUN_AGENT_USAGE_ADD_SOFTWARE
+    usage flags are only valid if the #STUN_COMPATIBILITY_RFC5389 or
+    #STUN_COMPATIBILITY_WLM2009 @compatibility is used
+    </para>
+ </note>
+ */
 void stun_agent_init (StunAgent *agent, const uint16_t *known_attributes,
-    StunCompatibility compatibility, uint32_t usage_flags);
+    StunCompatibility compatibility, StunAgentUsageFlags usage_flags);
+
+/**
+ * stun_agent_validate:
+ * @agent: The #StunAgent
+ * @msg: The #StunMessage to build
+ * @buffer: The data buffer of the STUN message
+ * @buffer_len: The length of @buffer
+ * @validater: A #StunMessageIntegrityValidate function callback that will
+ * be called if the agent needs to validate a MESSAGE-INTEGRITY attribute. It
+ * will only be called if the agent finds a message that needs authentication
+ * and a USERNAME is present in the STUN message, but no password is known.
+ * The validater will not be called if the #STUN_AGENT_USAGE_IGNORE_CREDENTIALS
+ * usage flag is set on the agent, and it will always be called if the
+ * #STUN_AGENT_USAGE_FORCE_VALIDATER usage flag is set on the agent.
+ * @validater_data: A user data to give to the @validater callback when it gets
+ * called.
+ *
+ * This function is used to validate an inbound STUN message and transform its
+ * data buffer into a #StunMessage. It will take care of various validation
+ * algorithms to make sure that the STUN message is valid and correctly
+ * authenticated.
+ * <para> See also: stun_agent_default_validater() </para>
+ * Returns: A #StunValidationStatus
+ <note>
+   <para>
+   if the return value is different from #STUN_VALIDATION_NOT_STUN or
+   #STUN_VALIDATION_INCOMPLETE_STUN, then the @msg argument will contain a valid
+   STUN message that can be used.
+   This means that you can use the @msg variable as the @request argument to
+   functions like stun_agent_init_error() or
+   stun_agent_build_unknown_attributes_error().
+   If the return value is #STUN_VALIDATION_BAD_REQUEST,
+   #STUN_VALIDATION_UNAUTHORIZED or #STUN_VALIDATION_UNAUTHORIZED_BAD_REQUEST
+   then the @key in the #StunMessage will not be set, so that error responses
+   will not have a MESSAGE-INTEGRITY attribute.
+   </para>
+ </note>
+ */
 StunValidationStatus stun_agent_validate (StunAgent *agent, StunMessage *msg,
     const uint8_t *buffer, size_t buffer_len,
     StunMessageIntegrityValidate validater, void * validater_data);
+
+/**
+ * stun_agent_init_request:
+ * @agent: The #StunAgent
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use in the #StunMessage
+ * @buffer_len: The length of the buffer
+ * @m: The #StunMethod of the request
+ *
+ * Creates a new STUN message of class #STUN_REQUEST and with the method @m
+ * Returns: %TRUE if the message was initialized correctly, %FALSE otherwise
+ */
 bool stun_agent_init_request (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len, StunMethod m);
+
+/**
+ * stun_agent_init_indication:
+ * @agent: The #StunAgent
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use in the #StunMessage
+ * @buffer_len: The length of the buffer
+ * @m: The #StunMethod of the indication
+ *
+ * Creates a new STUN message of class #STUN_INDICATION and with the method @m
+ * Returns: %TRUE if the message was initialized correctly, %FALSE otherwise
+ */
 bool stun_agent_init_indication (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len, StunMethod m);
+
+/**
+ * stun_agent_init_response:
+ * @agent: The #StunAgent
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use in the #StunMessage
+ * @buffer_len: The length of the buffer
+ * @request: The #StunMessage of class #STUN_REQUEST that this response is for
+ *
+ * Creates a new STUN message of class #STUN_RESPONSE and with the same method
+ * and transaction ID as the message @request. This will also copy the pointer
+ * to the key that was used to authenticate the request, so you won't need to
+ * specify the key with stun_agent_finish_message()
+ * Returns: %TRUE if the message was initialized correctly, %FALSE otherwise
+ */
 bool stun_agent_init_response (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len, const StunMessage *request);
+
+/**
+ * stun_agent_init_error:
+ * @agent: The #StunAgent
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use in the #StunMessage
+ * @buffer_len: The length of the buffer
+ * @request: The #StunMessage of class #STUN_REQUEST that this error response
+ * is for
+ * @err: The #StunError to put in the ERROR-CODE attribute of the error response
+ *
+ * Creates a new STUN message of class #STUN_ERROR and with the same method
+ * and transaction ID as the message @request. This will also copy the pointer
+ * to the key that was used to authenticate the request (if authenticated),
+ * so you won't need to specify the key with stun_agent_finish_message().
+ * It will then add the ERROR-CODE attribute with code @err and the associated
+ * string.
+ * Returns: %TRUE if the message was initialized correctly, %FALSE otherwise
+ */
 bool stun_agent_init_error (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len, const StunMessage *request,
     StunError err);
+
+/**
+ * stun_agent_build_unknown_attributes_error:
+ * @agent: The #StunAgent
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use in the #StunMessage
+ * @buffer_len: The length of the buffer
+ * @request: The #StunMessage of class #STUN_REQUEST that this response is for
+ *
+ * Creates a new STUN message of class #STUN_ERROR and with the same method
+ * and transaction ID as the message @request.  It will then add the ERROR-CODE
+ * attribute with code #STUN_ERROR_UNKNOWN_ATTRIBUTE and add all the unknown
+ * mandatory attributes from the @request STUN message in the
+ * #STUN_ATTRIBUTE_UNKNOWN_ATTRIBUTES attribute, it will then finish the message
+ * by calling stun_agent_finish_message()
+ * Returns: The size of the message built
+ */
 size_t stun_agent_build_unknown_attributes_error (StunAgent *agent,
     StunMessage *msg, uint8_t *buffer, size_t buffer_len,
     const StunMessage *request);
+
+
+/**
+ * stun_agent_finish_message:
+ * @agent: The #StunAgent
+ * @msg: The #StunMessage to finish
+ * @key: The key to use for the MESSAGE-INTEGRITY attribute
+ * @key_len: The length of the @key
+ *
+ * This function will 'finish' a message and make it ready to be sent. It will
+ * add the MESSAGE-INTEGRITY and FINGERPRINT attributes if necessary. If the
+ * STUN message has a #STUN_REQUEST class, it will save the transaction id of
+ * the message in the agent for future matching of the response.
+ * Returns: The final size of the message built
+ */
 size_t stun_agent_finish_message (StunAgent *agent, StunMessage *msg,
    const uint8_t *key, size_t key_len);
 
diff --git a/stun/stunmessage.h b/stun/stunmessage.h
index a1bb8f7..7b046e9 100644
--- a/stun/stunmessage.h
+++ b/stun/stunmessage.h
@@ -36,6 +36,18 @@
 #define _STUN_MESSAGE_H
 
 
+/**
+ * SECTION:stunmessage
+ * @short_description: STUN messages parsing and formatting functions
+ * @see_also: #StunAgent
+ * @stability: Stable
+ *
+ * The STUN Messages API allows you to create STUN messages easily as well as to
+ * parse existing messages.
+ *
+ */
+
+
 #ifdef _WIN32
 #include "win32_common.h"
 #else
@@ -351,6 +363,8 @@ typedef uint8_t StunTransactionId[STUN_MESSAGE_TRANS_ID_LEN];
  * "Active Destination Already Set" error as defined in TURN draft 04.
  * @STUN_ERROR_UNSUPPORTED_FAMILY: The ERROR-CODE value for the
  * "Address Family not Supported" error as defined in TURN IPV6 Draft 05.
+ * @STUN_ERROR_WRONG_CREDENTIALS: The ERROR-CODE value for the
+ * "Wrong Credentials" error as defined in TURN Draft 12.
  * @STUN_ERROR_UNSUPPORTED_TRANSPORT:he ERROR-CODE value for the
  * "Unsupported Transport Protocol" error as defined in TURN Draft 12.
  * @STUN_ERROR_INVALID_IP: The ERROR-CODE value for the
@@ -802,8 +816,8 @@ StunMessageReturn stun_message_append_error (StunMessage * msg,
  * provide us with the length of the STUN message.
  *
  * Returns: The length of the valid STUN message in the buffer.
- * See #STUN_MESSAGE_BUFFER_INCOMPLETE
- * See #STUN_MESSAGE_BUFFER_INVALID
+ * <para> See also: #STUN_MESSAGE_BUFFER_INCOMPLETE </para>
+ * <para> See also: #STUN_MESSAGE_BUFFER_INVALID </para>
  */
 int stun_message_validate_buffer_length (const uint8_t *msg, size_t length);
 
diff --git a/stun/usages/bind.h b/stun/usages/bind.h
index 938395c..f5db55f 100644
--- a/stun/usages/bind.h
+++ b/stun/usages/bind.h
@@ -55,6 +55,19 @@
 extern "C" {
 # endif
 
+/**
+ * StunUsageBindReturn:
+ * @STUN_USAGE_BIND_RETURN_SUCCESS: The binding usage succeeded
+ * @STUN_USAGE_BIND_RETURN_ERROR: There was an unknown error in the bind usage
+ * @STUN_USAGE_BIND_RETURN_INVALID: The message is invalid and should be ignored
+ * @STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER: The binding request has an
+ * ALTERNATE-SERVER attribute
+ * @STUN_USAGE_BIND_RETURN_TIMEOUT: The binding was unsuccessful because it has
+ * timed out.
+ *
+ * Return value of stun_usage_bind_process() and stun_usage_bind_run() which
+ * allows you to see what status the function call returned.
+ */
 typedef enum {
   STUN_USAGE_BIND_RETURN_SUCCESS,
   STUN_USAGE_BIND_RETURN_ERROR,
@@ -64,17 +77,72 @@ typedef enum {
 } StunUsageBindReturn;
 
 
+/**
+ * stun_usage_bind_create:
+ * @agent: The #StunAgent to use to create the binding request
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use for creating the #StunMessage
+ * @buffer_len: The size of the @buffer
+ *
+ * Create a new STUN binding request to use with a STUN server.
+ * Returns: The length of the built message.
+ */
 size_t stun_usage_bind_create (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len);
 
+/**
+ * stun_usage_bind_process:
+ * @msg: The #StunMessage to process
+ * @addr: A pointer to a #sockaddr structure to fill with the mapped address
+ * that the STUN server gives us
+ * @addrlen: The length of @addr
+ * @alternate_server: A pointer to a #sockaddr structure to fill with the
+ * address of an alternate server to which we should send our new STUN
+ * binding request, in case the currently used STUN server is requesting the use
+ * of an alternate server. This argument will only be filled if the return value
+ * of the function is #STUN_USAGE_BIND_RETURN_ALTERNATE_SERVER
+ * @alternate_server_len: The length of @alternate_server
+ *
+ * Process a STUN binding response and extracts the mapped address from the STUN
+ * message. Also checks for the ALTERNATE-SERVER attribute.
+ * Returns: A #StunUsageBindReturn value.
+ * Note that #STUN_USAGE_BIND_RETURN_TIMEOUT cannot be returned by this function
+ */
 StunUsageBindReturn stun_usage_bind_process (StunMessage *msg,
     struct sockaddr *addr, socklen_t *addrlen,
     struct sockaddr *alternate_server, socklen_t *alternate_server_len);
 
+/**
+ * stun_usage_bind_keepalive:
+ * @agent: The #StunAgent to use to build the message
+ * @msg: The #StunMessage to build
+ * @buf: The buffer to use for creating the #StunMessage
+ * @len: The size of the @buf
+ *
+ * Creates a STUN binding indication that can be used for a keepalive.
+ * Since this is an indication message, no STUN response will be generated
+ * and it can only be used as a keepalive message.
+ * Returns: The length of the message to send
+ */
 size_t stun_usage_bind_keepalive (StunAgent *agent, StunMessage *msg,
     uint8_t *buf, size_t len);
 
-
+/**
+ * stun_usage_bind_run:
+ * @srv: A pointer to the #sockaddr structure representing the STUN server's
+ * address
+ * @srvlen: The length of @srv
+ * @addr: A pointer to a #sockaddr structure to fill with the mapped address
+ * that the STUN server gives us
+ * @addrlen: The length of @addr
+ *
+ * This is a convenience function that will do a synchronous Binding request to
+ * a server and wait for its answer. It will use the #StunUsageTrans and
+ * #StunUsageTimer usages to send the request and handle the response.
+ * Returns: A #StunUsageBindReturn.
+ * Possible return values are #STUN_USAGE_BIND_RETURN_SUCCESS,
+ * #STUN_USAGE_BIND_RETURN_ERROR and #STUN_USAGE_BIND_RETURN_TIMEOUT
+ */
 StunUsageBindReturn stun_usage_bind_run (const struct sockaddr *srv,
     socklen_t srvlen, struct sockaddr *addr, socklen_t *addrlen);
 
diff --git a/stun/usages/ice.h b/stun/usages/ice.h
index 7cc9a83..d515b0e 100644
--- a/stun/usages/ice.h
+++ b/stun/usages/ice.h
@@ -47,12 +47,40 @@
 extern "C" {
 # endif
 
+/**
+ * StunUsageIceCompatibility:
+ * @STUN_USAGE_ICE_COMPATIBILITY_DRAFT19: The ICE compatibility with draft 19
+ * @STUN_USAGE_ICE_COMPATIBILITY_GOOGLE: The ICE compatibility with Google's
+ * implementation of ICE
+ * @STUN_USAGE_ICE_COMPATIBILITY_MSN: The ICE compatibility with MSN's
+ * implementation of ICE
+ *
+ * This enum defines which compatibility modes this ICE usage can use
+ */
 typedef enum {
   STUN_USAGE_ICE_COMPATIBILITY_DRAFT19,
   STUN_USAGE_ICE_COMPATIBILITY_GOOGLE,
   STUN_USAGE_ICE_COMPATIBILITY_MSN,
 } StunUsageIceCompatibility;
 
+
+/**
+ * StunUsageIceReturn:
+ * @STUN_USAGE_ICE_RETURN_SUCCESS: The function succeeded
+ * @STUN_USAGE_ICE_RETURN_ERROR: There was an unspecified error
+ * @STUN_USAGE_ICE_RETURN_INVALID: The message is invalid for processing
+ * @STUN_USAGE_ICE_RETURN_ROLE_CONFLICT: A role conflict was detected
+ * @STUN_USAGE_ICE_RETURN_INVALID_REQUEST: The message is an not a request
+ * @STUN_USAGE_ICE_RETURN_INVALID_METHOD: The method of the request is invalid
+ * @STUN_USAGE_ICE_RETURN_MEMORY_ERROR: The buffer size is too small to hold
+ * the STUN reply
+ * @STUN_USAGE_ICE_RETURN_INVALID_ADDRESS: The mapped address argument has
+ * an invalid address family
+ *
+ * Return value of stun_usage_ice_conncheck_process() and
+ * stun_usage_ice_conncheck_create_reply() which allows you to see what
+ * status the function call returned.
+ */
 typedef enum {
   STUN_USAGE_ICE_RETURN_SUCCESS,
   STUN_USAGE_ICE_RETURN_ERROR,
@@ -65,7 +93,30 @@ typedef enum {
 } StunUsageIceReturn;
 
 
-
+/**
+ * stun_usage_ice_conncheck_create:
+ * @agent: The #StunAgent to use to build the request
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use for creating the #StunMessage
+ * @buffer_len: The size of the @buffer
+ * @username: The username to use in the request
+ * @username_len: The length of @username
+ * @password: The key to use for building the MESSAGE-INTEGRITY
+ * @password_len: The length of @password
+ * @cand_use: Set to %TRUE to append the USE-CANDIDATE flag to the request
+ * @controlling: Set to %TRUE if you are the controlling agent or set to
+ * %FALSE if you are the controlled agent.
+ * @priority: The value of the PRIORITY attribute
+ * @tie: The value of the tie-breaker to put in the ICE-CONTROLLED or
+ * ICE-CONTROLLING attribute
+ * @compatibility: The compatibility mode to use for building the conncheck
+ * request
+ *
+ * Builds an ICE connectivity check STUN message.
+ * If the compatibility is not #STUN_USAGE_ICE_COMPATIBILITY_DRAFT19, the
+ * @cand_use, @controlling, @priority and @tie arguments are not used.
+ * Returns: The length of the message built.
+ */
 size_t
 stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len,
@@ -75,34 +126,54 @@ stun_usage_ice_conncheck_create (StunAgent *agent, StunMessage *msg,
     uint64_t tie, StunUsageIceCompatibility compatibility);
 
 
+/**
+ * stun_usage_ice_conncheck_process:
+ * @msg: The #StunMessage to process
+ * @addr: A pointer to a #sockaddr structure to fill with the mapped address
+ * that the STUN connectivity check response contains
+ * @addrlen: The length of @addr
+ * @compatibility: The compatibility mode to use for processing the conncheck
+ * response
+ *
+ * Process an ICE connectivity check STUN message and retreive the
+ * mapped address from the message
+ * <para> See also stun_usage_ice_conncheck_priority() and
+ * stun_usage_ice_conncheck_use_candidate() </para>
+ * Returns: A #StunUsageIceReturn value
+ */
 StunUsageIceReturn stun_usage_ice_conncheck_process (StunMessage *msg,
     struct sockaddr *addr, socklen_t *addrlen,
     StunUsageIceCompatibility compatibility);
 
 /**
- * Tries to parse a STUN connectivity check (Binding request) and format a
- * response accordingly.
+ * stun_usage_ice_conncheck_create_reply:
+ * @agent: The #StunAgent to use to build the response
+ * @req: The original STUN request to reply to
+ * @msg: The #StunMessage to build
+ * @buf: The buffer to use for creating the #StunMessage
+ * @plen: A pointer containing the size of the @buffer on input.
+ * Will contain the length of the message built on output.
+ * @src: A pointer to a #sockaddr structure containing the source address from
+ * which the request was received. Will be used as the mapped address in the
+ * response
+ * @srclen: The length of @addr
+ * @control: Set to %TRUE if you are the controlling agent or set to
+ * %FALSE if you are the controlled agent.
+ * @tie: The value of the tie-breaker to put in the ICE-CONTROLLED or
+ * ICE-CONTROLLING attribute
+ * @compatibility: The compatibility mode to use for building the conncheck
+ * response
  *
- * @param buf [OUT] output buffer to write a Binding response to. May refer
- * to the same buffer space as the request message.
- * @param plen [IN/OUT] output buffer size on entry, response length on exit
- * @param msg pointer to the first byte of the binding request
- * @param src socket address the message was received from
- * @param srclen byte length of the socket address
- * @param username STUN username
- * @param password HMAC secret password
- * @param control [IN/OUT] whether we are controlling ICE or not
- * @param tie tie breaker value for ICE role determination
- *
- * @return 0 if successful (@a rbuf contains a <b>non-error</b> response),
- * EINVAL: malformatted request message or socket address,
- * EAFNOSUPPORT: unsupported socket address family,
- * EPROTO: unsupported request message type or parameter,
- * ENOBUFS: insufficient response buffer space.
- * EACCES: ICE role conflict occurred, please recheck the flag at @a control
- *
- * In case of error, the value at @a plen is set to the size of an error
- * response, or 0 if no error response should be sent.
+ * Tries to parse a STUN connectivity check request and builds a
+ * response accordingly.
+ <note>
+   <para>
+     In case of error, the @msg is filled with the appropriate error response
+     to be sent and the value of @plen is set to the size of that message.
+     If @plen has a size of 0, then no error response should be sent.
+   </para>
+ </note>
+ * Returns: A #StunUsageIceReturn value
  */
 StunUsageIceReturn
 stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req,
@@ -112,16 +183,20 @@ stun_usage_ice_conncheck_create_reply (StunAgent *agent, StunMessage *req,
     StunUsageIceCompatibility compatibility);
 
 /**
+ * stun_usage_ice_conncheck_priority:
+ * @msg: The #StunMessage to parse
+ *
  * Extracts the priority from a STUN message.
- * @param msg valid STUN message.
- * @return host byte order priority, or 0 if not specified.
+ * Returns: host byte order priority, or 0 if not specified.
  */
 uint32_t stun_usage_ice_conncheck_priority (const StunMessage *msg);
 
 /**
- * Extracts the "use candidate" flag from a STUN message.
- * @param msg valid STUN message.
- * @return true if the flag is set, false if not.
+ * stun_usage_ice_conncheck_use_candidate:
+ * @msg: The #StunMessage to parse
+ *
+ * Extracts the USE-CANDIDATE attribute flag from a STUN message.
+ * Returns: %TRUE if the flag is set, %FALSE if not.
  */
 bool stun_usage_ice_conncheck_use_candidate (const StunMessage *msg);
 
diff --git a/stun/usages/timer.h b/stun/usages/timer.h
index 1e14171..87af166 100644
--- a/stun/usages/timer.h
+++ b/stun/usages/timer.h
@@ -48,12 +48,31 @@
 # include <time.h>
 #endif
 
-typedef struct stun_timer_s
-{
+/**
+ * StunTimer:
+ *
+ * An opaque structure representing a STUN transaction retransmission timer
+ */
+typedef struct stun_timer_s StunTimer;
+
+struct stun_timer_s {
   struct timeval deadline;
   unsigned delay;
-} StunTimer;
+};
+
 
+/**
+ * StunUsageTimerReturn:
+ * @STUN_USAGE_TIMER_RETURN_SUCCESS: The timer was refreshed successfully
+ * and there is nothing to be done
+ * @STUN_USAGE_TIMER_RETURN_RETRANSMIT: The timer expired and the message
+ * should be retransmitted now.
+ * @STUN_USAGE_TIMER_RETURN_TIMEOUT: The timer expired as well as all the
+ * retransmissions, the transaction timed out
+ *
+ * Return value of stun_usage_timer_refresh() which provides you with status
+ * information on the timer.
+ */
 typedef enum {
   STUN_USAGE_TIMER_RETURN_SUCCESS,
   STUN_USAGE_TIMER_RETURN_RETRANSMIT,
@@ -65,20 +84,41 @@ extern "C" {
 # endif
 
 /**
+ * stun_timer_start:
+ * @timer: The #StunTimer to start
+ *
  * Starts a STUN transaction retransmission timer.
- * @param timer structure for internal timer state
+ * This should be called as soon as you send the message for the first time on
+ * a UDP socket
  */
 void stun_timer_start (StunTimer *timer);
+
+/**
+ * stun_timer_start_reliable:
+ * @timer: The #StunTimer to start
+ *
+ * Starts a STUN transaction retransmission timer for a reliable transport.
+ * This should be called as soon as you send the message for the first time on
+ * a TCP socket
+ */
 void stun_timer_start_reliable (StunTimer *timer);
 
 /**
+ * stun_timer_refresh:
+ * @timer: The #StunTimer to refresh
+ *
  * Updates a STUN transaction retransmission timer.
- * @param timer internal timer state
- * @return -1 if the transaction timed out,
- * 0 if the transaction should be retransmitted,
- * otherwise milliseconds left until next time out or retransmit.
+ * Returns: A #StunUsageTimerReturn telling you what to do next
  */
 StunUsageTimerReturn stun_timer_refresh (StunTimer *timer);
+
+/**
+ * stun_timer_remainder:
+ * @timer: The #StunTimer to query
+ *
+ * Query the timer on the time left before the next refresh should be done
+ * Returns: The time remaining for the timer to expire in milliseconds
+ */
 unsigned stun_timer_remainder (const StunTimer *timer);
 
 # ifdef __cplusplus
diff --git a/stun/usages/turn.h b/stun/usages/turn.h
index 645c1bf..a3085f6 100644
--- a/stun/usages/turn.h
+++ b/stun/usages/turn.h
@@ -86,6 +86,21 @@ typedef enum {
   STUN_USAGE_TURN_COMPATIBILITY_MSN,
 } StunUsageTurnCompatibility;
 
+/**
+ * StunUsageTurnReturn:
+ * @STUN_USAGE_TURN_RETURN_RELAY_SUCCESS: The response was successful and a relay
+ * address is provided
+ * @STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS: The response was successful and a
+ * relay address as well as a mapped address are provided
+ * @STUN_USAGE_TURN_RETURN_ERROR: The response resulted in an error
+ * @STUN_USAGE_TURN_RETURN_INVALID: The response is not a valid response
+ * @STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER: The server requests the message
+ * to be sent to an alternate server
+ *
+ * Return value of stun_usage_turn_process() and
+ * stun_usage_turn_refresh_process() which allows you to see what status the
+ * function call returned.
+ */
 typedef enum {
   STUN_USAGE_TURN_RETURN_RELAY_SUCCESS,
   STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS,
@@ -95,6 +110,40 @@ typedef enum {
 } StunUsageTurnReturn;
 
 
+/**
+ * stun_usage_turn_create:
+ * @agent: The #StunAgent to use to build the request
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use for creating the #StunMessage
+ * @buffer_len: The size of the @buffer
+ * @previous_response: If this is the first request you are sending, set this
+ * argument to NULL, if it's a subsequent request you are building, then set this
+ * argument to the response you have received. This argument is used for building
+ * long term credentials (using the REALM and NONCE attributes) as well as for
+ * getting the RESERVATION-TOKEN attribute when you previously requested an
+ * allocation which reserved two ports
+ * @request_ports: Specify how you want to request the allocated port(s).
+ * This is only used if the compatibility is set to
+ * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
+ * <para>See #StunUsageTurnRequestPorts </para>
+ * @bandwidth: The bandwidth to request from the server for the allocation. If
+ * this value is negative, then no BANDWIDTH attribute is added to the request.
+ * This is only used if the compatibility is set to
+ * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
+ * @lifetime: The lifetime of the allocation to request from the server. If
+ * this value is negative, then no LIFETIME attribute is added to the request.
+ * This is only used if the compatibility is set to
+ * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
+ * @username: The username to use in the request
+ * @username_len: The length of @username
+ * @password: The key to use for building the MESSAGE-INTEGRITY
+ * @password_len: The length of @password
+ * @compatibility: The compatibility mode to use for building the Allocation
+ * request
+ *
+ * Create a new TURN Allocation request
+ * Returns: The length of the message to send
+ */
 size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len,
     StunMessage *previous_response,
@@ -104,6 +153,30 @@ size_t stun_usage_turn_create (StunAgent *agent, StunMessage *msg,
     uint8_t *password, size_t password_len,
     StunUsageTurnCompatibility compatibility);
 
+/**
+ * stun_usage_turn_create_refresh:
+ * @agent: The #StunAgent to use to build the request
+ * @msg: The #StunMessage to build
+ * @buffer: The buffer to use for creating the #StunMessage
+ * @buffer_len: The size of the @buffer
+ * @previous_response: If this is the first request you are sending, set this
+ * argument to NULL, if it's a subsequent request you are building, then set this
+ * argument to the response you have received. This argument is used for building
+ * long term credentials (using the REALM and NONCE attributes)
+ * @lifetime: The lifetime of the allocation to request from the server. If
+ * this value is negative, then no LIFETIME attribute is added to the request.
+ * This is only used if the compatibility is set to
+ * #STUN_USAGE_TURN_COMPATIBILITY_DRAFT9
+ * @username: The username to use in the request
+ * @username_len: The length of @username
+ * @password: The key to use for building the MESSAGE-INTEGRITY
+ * @password_len: The length of @password
+ * @compatibility: The compatibility mode to use for building the Allocation
+ * request
+ *
+ * Create a new TURN Refresh request
+ * Returns: The length of the message to send
+ */
 size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg,
     uint8_t *buffer, size_t buffer_len,
     StunMessage *previous_response, int32_t lifetime,
@@ -111,6 +184,32 @@ size_t stun_usage_turn_create_refresh (StunAgent *agent, StunMessage *msg,
     uint8_t *password, size_t password_len,
     StunUsageTurnCompatibility compatibility);
 
+/**
+ * stun_usage_turn_process:
+ * @msg: The message containing the response
+ * @relay_addr: A pointer to a #sockaddr structure to fill with the relay address
+ * that the TURN server allocated for us
+ * @relay_addrlen: The length of @relay_addr
+ * @addr: A pointer to a #sockaddr structure to fill with the mapped address
+ * that the STUN response contains.
+ * This argument will only be filled if the return value
+ * of the function is #STUN_USAGE_TURN_RETURN_MAPPED_SUCCESS
+ * @addrlen: The length of @addr
+ * @alternate_server: A pointer to a #sockaddr structure to fill with the
+ * address of an alternate server to which we should send our new STUN
+ * Allocate request, in case the currently used TURN server is requesting the use
+ * of an alternate server. This argument will only be filled if the return value
+ * of the function is #STUN_USAGE_TURN_RETURN_ALTERNATE_SERVER
+ * @alternate_server_len: The length of @alternate_server
+ * @bandwidth: A pointer to fill with the bandwidth the TURN server allocated us
+ * @lifetime: A pointer to fill with the lifetime of the allocation
+ * @compatibility: The compatibility mode to use for processing the Allocation
+ * response
+ *
+ * Process a TURN Allocate response and extract the necessary information from
+ * the message
+ * Returns: A #StunUsageTurnReturn value
+ */
 StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg,
     struct sockaddr *relay_addr, socklen_t *relay_addrlen,
     struct sockaddr *addr, socklen_t *addrlen,
@@ -118,6 +217,19 @@ StunUsageTurnReturn stun_usage_turn_process (StunMessage *msg,
     uint32_t *bandwidth, uint32_t *lifetime,
     StunUsageTurnCompatibility compatibility);
 
+/**
+ * stun_usage_turn_refresh_process:
+ * @msg: The message containing the response
+ * @lifetime: A pointer to fill with the lifetime of the allocation
+ * @compatibility: The compatibility mode to use for processing the Refresh
+ * response
+ *
+ * Process a TURN Refresh response and extract the necessary information from
+ * the message
+ * Returns: A #StunUsageTurnReturn value. A #STUN_USAGE_TURN_RETURN_RELAY_SUCCESS
+ * means the Refresh was successful, but no relay address is given (kept the same
+ * as for the original allocation)
+ */
 StunUsageTurnReturn stun_usage_turn_refresh_process (StunMessage *msg,
     uint32_t *lifetime, StunUsageTurnCompatibility compatibility);