Update the docs to include everything

5 files changed, 342 insertions, 35 deletions

diff --git a/agent/address.h b/agent/address.h
index b5d4436..89c5740 100644
--- a/agent/address.h
+++ b/agent/address.h
@@ -38,6 +38,16 @@
 #ifndef _ADDRESS_H
 #define _ADDRESS_H
 
+/**
+ * SECTION:address
+ * @short_description: IP address convenience library
+ * @stability: Stable
+ *
+ * The #NiceAddress structure will allow you to easily set/get and modify an IPv4
+ * or IPv6 address in order to communicate with the #NiceAgent.
+ */
+
+
 #include <glib.h>
 
 #ifdef G_OS_WIN32
@@ -52,11 +62,15 @@
 
 G_BEGIN_DECLS
 
-#define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN
-
-typedef struct _NiceAddress NiceAddress;
 
-/* note: clients need to know the storage size, so needs to be public */
+/**
+ * NiceAddress:
+ * @addr: Generic sockaddr address
+ * @ip4: IPv4 sockaddr address
+ * @ip6: IPv6 sockaddr address
+ *
+ * The #NiceAddress structure that represents an IPv4 or IPv6 address.
+ */
 struct _NiceAddress
 {
   union
@@ -68,45 +82,193 @@ struct _NiceAddress
 };
 
 
+/**
+ * NICE_ADDRESS_STRING_LEN:
+ *
+ * The maximum string length representation of an address.
+ * When using nice_address_to_string() make sure the string has a size of
+ * at least %NICE_ADDRESS_STRING_LEN
+ */
+#define NICE_ADDRESS_STRING_LEN INET6_ADDRSTRLEN
+
+typedef struct _NiceAddress NiceAddress;
+
+
+/**
+ * nice_address_init:
+ * @addr: The #NiceAddress to init
+ *
+ * Initialize a #NiceAddress into an undefined address
+ */
+void
+nice_address_init (NiceAddress *addr);
+
+/**
+ * nice_address_new:
+ *
+ * Create a new #NiceAddress with undefined address
+ * You must free it with nice_address_free()
+ *
+ * Returns: The new #NiceAddress
+ */
 NiceAddress *
 nice_address_new (void);
 
+/**
+ * nice_address_free:
+ * @addr: The #NiceAddress to free
+ *
+ * Frees a #NiceAddress created with nice_address_new() or nice_address_dup()
+ */
 void
 nice_address_free (NiceAddress *addr);
 
+/**
+ * nice_address_dup:
+ * @addr: The #NiceAddress to dup
+ *
+ * Creates a new #NiceAddress with the same address as @addr
+ *
+ * Returns: The new #NiceAddress
+ */
 NiceAddress *
 nice_address_dup (const NiceAddress *addr);
 
+
+/**
+ * nice_address_set_ipv4:
+ * @addr: The #NiceAddress to modify
+ * @addr_ipv4: The IPv4 address
+ *
+ * Set @addr to an IPv4 address using the data from @addr_ipv4
+ *
+ <note>
+  <para>
+   This function will reset the port to 0, so make sure you call it before
+   nice_address_set_port()
+  </para>
+ </note>
+ */
 void
 nice_address_set_ipv4 (NiceAddress *addr, guint32 addr_ipv4);
 
+
+/**
+ * nice_address_set_ipv6:
+ * @addr: The #NiceAddress to modify
+ * @addr_ipv6: The IPv6 address
+ *
+ * Set @addr to an IPv6 address using the data from @addr_ipv6
+ *
+ <note>
+  <para>
+   This function will reset the port to 0, so make sure you call it before
+   nice_address_set_port()
+  </para>
+ </note>
+ */
 void
 nice_address_set_ipv6 (NiceAddress *addr, const guchar *addr_ipv6);
 
+
+/**
+ * nice_address_set_port:
+ * @addr: The #NiceAddress to modify
+ * @port: The port to set
+ *
+ * Set the port of @addr to @port
+ */
 void
 nice_address_set_port (NiceAddress *addr, guint port);
 
+/**
+ * nice_address_get_port:
+ * @addr: The #NiceAddress to query
+ *
+ * Retreive the port of @addr
+ *
+ * Returns: The port of @addr
+ */
 guint
 nice_address_get_port (const NiceAddress *addr);
 
+/**
+ * nice_address_set_from_string:
+ * @addr: The #NiceAddress to modify
+ * @str: The string to set
+ *
+ * Sets an IPv4 or IPv6 address from the string @str
+ *
+ * Returns: %TRUE if success, %FALSE on error
+ */
 gboolean
 nice_address_set_from_string (NiceAddress *addr, const gchar *str);
 
+/**
+ * nice_address_set_from_sockaddr:
+ * @addr: The #NiceAddress to modify
+ * @sin: The sockaddr to set
+ *
+ * Sets an IPv4 or IPv6 address from the sockaddr structure @sin
+ *
+ */
 void
 nice_address_set_from_sockaddr (NiceAddress *addr, const struct sockaddr *sin);
 
+
+/**
+ * nice_address_copy_to_sockaddr:
+ * @addr: The #NiceAddress to query
+ * @sin: The sockaddr to fill
+ *
+ * Fills the sockaddr structure @sin with the address contained in @addr
+ *
+ */
 void
 nice_address_copy_to_sockaddr (const NiceAddress *addr, struct sockaddr *sin);
 
+/**
+ * nice_address_equal:
+ * @a: First #NiceAddress to compare
+ * @b: Second #NiceAddress to compare
+ *
+ * Compares two #NiceAddress structures to see if they contain the same address
+ *
+ * Returns: %TRUE if @a and @b are the same address, %FALSE if they are different
+ */
 gboolean
 nice_address_equal (const NiceAddress *a, const NiceAddress *b);
 
+/**
+ * nice_address_to_string:
+ * @addr: The #NiceAddress to query
+ * @dst: The string to fill
+ *
+ * Transforms the address @addr into a human readable string
+ *
+ */
 void
 nice_address_to_string (const NiceAddress *addr, gchar *dst);
 
+/**
+ * nice_address_is_private:
+ * @addr: The #NiceAddress to query
+ *
+ * Verifies if the address in @addr is a private address or not
+ *
+ * Returns: %TRUE if @addr is a private address, %FALSE otherwise
+ */
 gboolean
 nice_address_is_private (const NiceAddress *addr);
 
+/**
+ * nice_address_is_valid:
+ * @addr: The #NiceAddress to query
+ *
+ * Validate whether the #NiceAddress @addr is a valid IPv4 or IPv6 address
+ *
+ * Returns: %TRUE if @addr is valid, %FALSE otherwise
+ */
 G_GNUC_WARN_UNUSED_RESULT
 gboolean
 nice_address_is_valid (const NiceAddress *addr);
diff --git a/agent/agent.c b/agent/agent.c
index 6aeadd5..1769799 100644
--- a/agent/agent.c
+++ b/agent/agent.c
@@ -193,7 +193,12 @@ nice_agent_class_init (NiceAgentClass *klass)
   gobject_class->dispose = nice_agent_dispose;
 
   /* install properties */
-
+  /**
+   * NiceAgent:main-context:
+   *
+   * A GLib main context is needed for all timeouts used by libnice.
+   * This is a property being set by the nice_agent_new() call.
+   */
   g_object_class_install_property (gobject_class, PROP_MAIN_CONTEXT,
       g_param_spec_pointer (
          "main-context",
@@ -201,6 +206,13 @@ nice_agent_class_init (NiceAgentClass *klass)
          "The GMainContext to use for timeouts",
          G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+  /**
+   * NiceAgent:compatibility:
+   *
+   * The Nice agent can work in various compatibility modes depending on
+   * what the application/peer needs.
+   * <para> See also: #NiceCompatibility</para>
+   */
   g_object_class_install_property (gobject_class, PROP_COMPATIBILITY,
       g_param_spec_uint (
          "compatibility",
@@ -264,7 +276,14 @@ nice_agent_class_init (NiceAgentClass *klass)
 
   /* install signals */
 
-  /* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id, guint state, gpointer self) */
+  /**
+   * NiceAgent::component-state-changed
+   * @stream_id: The ID of the stream
+   * @component_id: The ID of the component
+   * @state: The #NiceComponentState of the component
+   *
+   * This signal is fired whenever a component's state changes
+   */
   signals[SIGNAL_COMPONENT_STATE_CHANGED] =
       g_signal_new (
           "component-state-changed",
@@ -279,7 +298,13 @@ nice_agent_class_init (NiceAgentClass *klass)
           G_TYPE_UINT, G_TYPE_UINT, G_TYPE_UINT,
           G_TYPE_INVALID);
 
-  /* signature: void cb(NiceAgent *agent, gpointer self) */
+  /**
+   * NiceAgent::candidate-gathering-done:
+   * @stream_id: The ID of the stream
+   *
+   * This signal is fired whenever a stream has finished gathering its
+   * candidates after a call to nice_agent_gather_candidates()
+   */
   signals[SIGNAL_CANDIDATE_GATHERING_DONE] =
       g_signal_new (
           "candidate-gathering-done",
@@ -293,8 +318,16 @@ nice_agent_class_init (NiceAgentClass *klass)
           1,
           G_TYPE_UINT, G_TYPE_INVALID);
 
- /* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id, 
-                gchar *lfoundation, gchar* rfoundation, gpointer self) */
+  /**
+   * NiceAgent::new-selected-pair
+   * @stream_id: The ID of the stream
+   * @component_id: The ID of the component
+   * @lfoundation: The local foundation of the selected candidate pair
+   * @rfoundation: The remote foundation of the selected candidate pair
+   *
+   * This signal is fired once a candidate pair is selected for data transfer for
+   * a stream's component
+   */
   signals[SIGNAL_NEW_SELECTED_PAIR] =
       g_signal_new (
           "new-selected-pair",
@@ -309,7 +342,15 @@ nice_agent_class_init (NiceAgentClass *klass)
           G_TYPE_UINT, G_TYPE_UINT, G_TYPE_STRING, G_TYPE_STRING,
           G_TYPE_INVALID);
 
- /* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id, gchar *foundation) */
+  /**
+   * NiceAgent::new-candidate
+   * @stream_id: The ID of the stream
+   * @component_id: The ID of the component
+   * @foundation: The foundation of the new candidate
+   *
+   * This signal is fired when the agent discovers a new candidate
+   * <para> See also: #NiceAgent::candidates-gathering-done </para>
+   */
   signals[SIGNAL_NEW_CANDIDATE] =
       g_signal_new (
           "new-candidate",
@@ -324,7 +365,16 @@ nice_agent_class_init (NiceAgentClass *klass)
           G_TYPE_UINT, G_TYPE_UINT, G_TYPE_STRING,
           G_TYPE_INVALID);
 
- /* signature: void cb(NiceAgent *agent, guint stream_id, guint component_id, gchar *foundation) */
+  /**
+   * NiceAgent::new-remote-candidate
+   * @stream_id: The ID of the stream
+   * @component_id: The ID of the component
+   * @foundation: The foundation of the new candidate
+   *
+   * This signal is fired when the agent discovers a new remote candidate.
+   * This can happen with peer reflexive candidates.
+   * <para> See also: #NiceAgent::candidates-gathering-done </para>
+   */
   signals[SIGNAL_NEW_REMOTE_CANDIDATE] =
       g_signal_new (
           "new-remote-candidate",
@@ -339,7 +389,13 @@ nice_agent_class_init (NiceAgentClass *klass)
           G_TYPE_UINT, G_TYPE_UINT, G_TYPE_STRING,
           G_TYPE_INVALID);
 
-  /* signature: void cb(NiceAgent *agent, guint stream_id, gpointer self) */
+  /**
+   * NiceAgent::initial-binding-request-received
+   * @stream_id: The ID of the stream
+   *
+   * This signal is fired when we received our first binding request from
+   * the peer.
+   */
   signals[SIGNAL_INITIAL_BINDING_REQUEST_RECEIVED] =
       g_signal_new (
           "initial-binding-request-received",
diff --git a/agent/agent.h b/agent/agent.h
index e3baab6..e64b3c3 100644
--- a/agent/agent.h
+++ b/agent/agent.h
@@ -39,20 +39,84 @@
 #ifndef _AGENT_H
 #define _AGENT_H
 
+/**
+ * SECTION:agent
+ * @short_description:  ICE agent API implementation
+ * @see_also: #NiceCandidate
+ * @see_also: #NiceAddress
+ * @include: agent.h
+ * @stability: Stable
+ *
+ * The #NiceAgent is your main object when using libnice.
+ * It is the agent that will take care of everything relating to ICE.
+ * It will take care of discovering your local candidates and do
+ *  connectivity checks to create a stream of data between you and your peer.
+ *
+ <example>
+   <title>Simple example on how to use libnice</title>
+   <programlisting>
+   NiceAddress base_addr;
+   guint stream_id;
+   gchar buffer[] = "hello world!";
+   GSList *lcands = NULL;
+
+   // Create a nice agent
+   NiceAgent *agent = nice_agent_new (NULL, NICE_COMPATIBILITY_DRAFT19);
+
+   // Specify which local interface to use
+   nice_address_set_from_string (&base_addr, "127.0.0.1");
+   nice_agent_add_local_address (agent, &base_addr);
+
+   // Connect the signals
+   g_signal_connect (G_OBJECT (agent), "candidate-gathering-done",
+                     G_CALLBACK (cb_candidate_gathering_done), NULL);
+   g_signal_connect (G_OBJECT (lagent), "component-state-changed",
+                     G_CALLBACK (cb_component_state_changed), NULL);
+   g_signal_connect (G_OBJECT (lagent), "new-selected-pair",
+                     G_CALLBACK (cb_new_selected_pair), NULL);
+
+   // Create a new stream with one component and start gathering candidates
+   stream_id = nice_agent_add_stream (agent, 1);
+   nice_agent_gather_candidates (agent, stream_id);
+
+   // Attach to the component to receive the data
+   nice_agent_attach_recv (agent, stream_id, 1, NULL,
+                          cb_nice_recv, NULL);
+
+   // ... Wait until the signal candidate-gathering-done is fired ...
+   lcands = nice_agent_get_local_candidates(agent, stream_id, 1);
+
+   // ... Send local candidates to the peer and set the peer's remote candidates
+   nice_agent_set_remote_candidates (agent, stream_id, 1, rcands);
+
+   // ... Wait until the signal new-selected-pair is fired ...
+   // Send our message!
+   nice_agent_send (lagent, ls_id, 1, sizeof(buffer), buffer);
+
+   // Anything received will be received through the cb_nice_recv callback
+
+   // Destroy the object
+   g_object_unref(agent);
+
+   </programlisting>
+ </example>
+ */
+
+
 #include <glib-object.h>
 
+/**
+ * NiceAgent:
+ *
+ * The #NiceAgent is the main GObject of the libnice library and represents
+ * the ICE agent.
+ */
 typedef struct _NiceAgent NiceAgent;
 
 #include "address.h"
 #include "candidate.h"
 #include "debug.h"
 
-/**
- * SECTION:agent
- * @short_description:  ICE agent API implementation
- *
- * 
- */
 
 G_BEGIN_DECLS
 
@@ -78,7 +142,6 @@ G_BEGIN_DECLS
   (G_TYPE_INSTANCE_GET_CLASS ((obj), \
   NICE_TYPE_AGENT, NiceAgentClass))
 
-
 typedef struct _NiceAgentClass NiceAgentClass;
 
 struct _NiceAgentClass
@@ -109,6 +172,7 @@ GType nice_agent_get_type (void);
  * is now final
  * @NICE_COMPONENT_STATE_FAILED: Connectivity checks have been completed,
  * but connectivity was not established
+ * @NICE_COMPONENT_STATE_LAST: Dummy state
  *
  * An enum representing the state of a component.
  * See #NiceAgent::component-state-changed
@@ -151,6 +215,7 @@ typedef enum
  * @NICE_COMPATIBILITY_DRAFT19: Use compatibility for ICE Draft 19 specs
  * @NICE_COMPATIBILITY_GOOGLE: Use compatibility for Google Talk specs
  * @NICE_COMPATIBILITY_MSN: Use compatibility for MSN Messenger specs
+ * @NICE_COMPATIBILITY_LAST: Dummy last compatibility mode
  *
  * An enum to specify which compatible specifications the #NiceAgent should use.
  * Use with nice_agent_new()
@@ -187,8 +252,9 @@ typedef void (*NiceAgentRecvFunc) (
  * @compat: The compatibility mode of the agent
  *
  * Create a new #NiceAgent.
+ * The returned object must be freed with g_object_unref()
  *
- * Returns: the new agent GObject
+ * Returns: The new agent GObject
  */
 NiceAgent *
 nice_agent_new (GMainContext *ctx, NiceCompatibility compat);
@@ -344,7 +410,8 @@ nice_agent_get_local_credentials (
  *
  <note>
    <para>
-    NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates
+    NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
+    for remote candidates
    </para>
  </note>
  *
@@ -372,11 +439,13 @@ nice_agent_add_remote_candidate (
  *
  <note>
    <para>
-    NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit for remote candidates
+    NICE_AGENT_MAX_REMOTE_CANDIDATES is the absolute maximum limit
+    for remote candidates
    </para>
  </note>
  *
- * Returns: The number of candidates added, negative on fatal (memory allocs) errors
+ * Returns: The number of candidates added,
+ * negative on fatal (memory allocs) errors
  **/
 int
 nice_agent_set_remote_candidates (
@@ -419,7 +488,8 @@ nice_agent_send (
  * @stream_id: The ID of the stream
  * @component_id: The ID of the component
  *
- * Retreive from the agent the list of all local candidates for a stream's component
+ * Retreive from the agent the list of all local candidates
+ * for a stream's component
  *
  <note>
    <para>
@@ -450,12 +520,13 @@ nice_agent_get_local_candidates (
  *
  <note>
    <para>
-     The caller owns the returned GSList but not the candidates contained within it.
+     The caller owns the returned GSList but not the candidates
+     contained within it.
    </para>
    <para>
      The list of remote candidates can change during processing.
-     The client should register for the #NiceAgent::new-remote-candidate signal to
-     get notification of new remote candidates.
+     The client should register for the #NiceAgent::new-remote-candidate signal
+     to get notified of new remote candidates.
    </para>
  </note>
  *
@@ -490,11 +561,12 @@ nice_agent_restart (
  * @stream_id: The ID of stream
  * @component_id: The ID of the component
  * @ctx: The Glib Mainloop Context to use for listening on the component
- * @func: The callback function to be called when data is received on the component
+ * @func: The callback function to be called when data is received on
+ * the stream's component
  * @data: user data associated with the callback
  *
- * Attaches the stream's component's sockets to the Glib Mainloop Context in order
- * to be notified whenever data becomes available for a component.
+ * Attaches the stream's component's sockets to the Glib Mainloop Context in
+ * order to be notified whenever data becomes available for a component.
  *
  * Returns: %TRUE on success, %FALSE if the stream or component IDs are invalid.
  */
@@ -543,8 +615,8 @@ nice_agent_set_selected_pair (
  * for a given stream's component. This is used to force the selection of
  * a specific remote candidate even when connectivity checks are failing
  * (e.g. non-ICE compatible candidates).
- * Calling this function will disable all further ICE processing (connection check,
- * state machine updates, etc). Note that keepalives will
+ * Calling this function will disable all further ICE processing
+ * (connection check, state machine updates, etc). Note that keepalives will
  * continue to be sent.
  *
  * Returns: %TRUE on success, %FALSE on failure
diff --git a/agent/candidate.h b/agent/candidate.h
index 0133bf0..64eda59 100644
--- a/agent/candidate.h
+++ b/agent/candidate.h
@@ -43,8 +43,13 @@
 /**
  * SECTION:candidate
  * @short_description: ICE candidate representation
+ * @see_also: #NiceAddress
+ * @stability: Stable
  *
- * 
+ * A representation of an ICE candidate. Make sure you read the ICE drafts[1] to
+ * understand correctly the concept of ICE candidates.
+ *
+ * [1] http://tools.ietf.org/wg/mmusic/draft-ietf-mmusic-ice/
  */
 
 
@@ -206,7 +211,8 @@ gfloat
 nice_candidate_msn_priority (NiceCandidate *candidate);
 
 guint32
-nice_candidate_ice_priority_full (guint type_pref, guint local_pref, guint component_id);
+nice_candidate_ice_priority_full (guint type_pref, guint local_pref,
+    guint component_id);
 
 guint32
 nice_candidate_ice_priority (const NiceCandidate *candidate);
diff --git a/agent/debug.h b/agent/debug.h
index d360772..eff1bc6 100644
--- a/agent/debug.h
+++ b/agent/debug.h
@@ -40,8 +40,19 @@
 /**
  * SECTION:debug
  * @short_description: Debug messages utility functions
+ * @stability: More flags are to come and a better API to
+ * enable/disable each flag should be added. Unstable
  *
- * 
+ * Libnice can output a lot of information when debug messages are enabled.
+ * This can significantly help track down problems and/or understand what
+ * it's doing.
+ * You can enable/disable the debug messages by calling nice_debug_enable()
+ * or nice_debug_disable() and choosing whether you want only ICE debug messages
+ * or also stun debug messages.
+ * By default, the debug messages are disabled, unless the environment variable
+ * NICE_DEBUG is set, in which case, it must contain a comma separated list of
+ * flags specifying which debug to enable. The flags can be "nice", "stun",
+ * or "all" to enable all debug messages.
  */