More documentation

3 files changed, 92 insertions, 1 deletions

diff --git a/gfbgraph/gfbgraph-common.c b/gfbgraph/gfbgraph-common.c
index 7a0271a..fa7c13a 100644
--- a/gfbgraph/gfbgraph-common.c
+++ b/gfbgraph/gfbgraph-common.c
@@ -24,7 +24,7 @@
 #define FACEBOOK_ENDPOINT "https://graph.facebook.com"
 
 /**
- * gfbgraog_new_rest_call:
+ * gfbgraph_new_rest_call:
  * @authorizer: a #GFBGraphAuthorizer.
  *
  * Create a new #RestProxyCall pointing to the Facebook Graph API url (https://graph.facebook.com)
diff --git a/gfbgraph/gfbgraph-connectable.c b/gfbgraph/gfbgraph-connectable.c
index 68c14ea..7561730 100644
--- a/gfbgraph/gfbgraph-connectable.c
+++ b/gfbgraph/gfbgraph-connectable.c
@@ -17,6 +17,18 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gfbgraph-connectable
+ * @title: GFBGraphConnectable
+ * @short_description: Connectable interface for nodes
+ * @include: gfbgraph/gfbgraph.h
+ *
+ * #GFBGraphConnectable interface allow the connection between nodes.
+ * You can see the posible (not necesary implemented) connections in
+ * the section "Connections" in any node object in the 
+ * <ulink url="https://developers.facebook.com/docs/reference/api/">Facebook Graph API documentation</ulink>
+ **/
+
 #include "gfbgraph-connectable.h"
 #include "gfbgraph-node.h"
 
@@ -36,6 +48,11 @@ gfbgraph_connectable_default_init (GFBGraphConnectableInterface *iface)
 static GHashTable*
 get_connections (GFBGraphConnectableInterface *iface)
 {
+        /* The GHashTable contains the connections for a node.
+         * The key must be the g_type_name() of a GFBGRAPH_TYPE_NODE, and the value
+         * must be the function name to call in order to retrieve the nodes connected
+         * to the GFBGraphNode indicated by GFBGRAPH_TYPE_NODE.
+         */
         GHashTable *connections;
 
         connections = iface->connections;
@@ -45,6 +62,16 @@ get_connections (GFBGraphConnectableInterface *iface)
         return connections;
 }
 
+/**
+ * gfbgraph_connectable_get_connection_post_params:
+ * @self: a #GFBGraphConnectable.
+ * @node_type: a #GType, required a #GFBGRAPH_TYPE_NODE or children.
+ *
+ * Get the params to be inserted in a request to the Facebook Graph API
+ * in order to append the node @self to a node of type @node_type.
+ *
+ * Returns: A string based #GHashTable with the params and his values or %NULL.
+ **/
 GHashTable*
 gfbgraph_connectable_get_connection_post_params (GFBGraphConnectable *self, GType node_type)
 {
@@ -60,6 +87,17 @@ gfbgraph_connectable_get_connection_post_params (GFBGraphConnectable *self, GTyp
         return iface->get_connection_post_params (self, node_type);
 }
 
+/**
+ * gfbgraph_connectable_parse_connected_data:
+ * @self: a #GFBGraphConnectable.
+ * @payload: a const #gchar with the response string from the Facebook Graph API.
+ * @error: (allow-none) a #GError.
+ *
+ * Parse the response contained in @payload when a gfbgraph_node_get_connection_nodes() was
+ * executed.
+ *
+ * Returns: a #GList of #GFBGraphNode created from the @payload or %NULL.
+ **/
 GList*
 gfbgraph_connectable_parse_connected_data (GFBGraphConnectable *self, const gchar *payload, GError **error)
 {
@@ -73,6 +111,18 @@ gfbgraph_connectable_parse_connected_data (GFBGraphConnectable *self, const gcha
         return iface->parse_connected_data (self, payload, error);
 }
 
+
+/**
+ * gfbgraph_connectable_is_connectable_to:
+ * @self: a #GFBGraphConnectable.
+ * @node_type: a #GType, required a #GFBGRAPH_TYPE_NODE or children.
+ *
+ * Check if @self object, normally a #GFBGraphNode implementing the #GFBGraphConnectable interface,
+ * has the possibility to be connected to another node of type @node_type.
+ *
+ * Returns: %TRUE in case that the @self object can be connected to a node of type @node_type,
+ * %FALSE otherwise.
+ **/
 gboolean
 gfbgraph_connectable_is_connectable_to (GFBGraphConnectable *self, GType node_type)
 {
@@ -88,6 +138,16 @@ gfbgraph_connectable_is_connectable_to (GFBGraphConnectable *self, GType node_ty
         return g_hash_table_contains (connections, g_type_name (node_type));
 }
 
+/**
+ * gfbgraph_connectable_get_connection_path:
+ * @self: a #GFBGraphConnectable.
+ * @node_type: a #GType, required a #GFBGRAPH_TYPE_NODE or children.
+ *
+ * Get the Facebook Graph API function path to retrieve the nodes connected with @node_type
+ * managed by the #GFBGraphConnectable object.
+ *
+ * Returns: a const #gchar with the function path or %NULL.
+ **/
 const gchar*
 gfbgraph_connectable_get_connection_path (GFBGraphConnectable *self, GType node_type)
 {
@@ -104,6 +164,21 @@ gfbgraph_connectable_get_connection_path (GFBGraphConnectable *self, GType node_
         return (const gchar *) g_hash_table_lookup (connections, g_type_name (node_type));
 }
 
+/**
+ * gfbgraph_connectable_default_parse_connected_data:
+ * @self: a #GFBGraphConnectable.
+ * @payload: a const #gchar with the response string from the Facebook Graph API.
+ * @error: (allow-none) a #GError or %NULL.
+ *
+ * In most cases, #GFBGraphConnectable implementers can use this function in order to parse
+ * the response when a gfbgraph_node_get_connection_nodes() is executed and the
+ * gfbgraph_connectable_parse_connected_data() was called.
+ *
+ * Normally, Facebook Graph API returns the connections in the same way, using JSON objects,
+ * with a root object called "data".
+ *
+ * Returns: 
+ **/
 GList*
 gfbgraph_connectable_default_parse_connected_data (GFBGraphConnectable *self, const gchar *payload, GError **error)
 {
diff --git a/gfbgraph/gfbgraph-goa-authorizer.c b/gfbgraph/gfbgraph-goa-authorizer.c
index 479430c..9c1cbe3 100644
--- a/gfbgraph/gfbgraph-goa-authorizer.c
+++ b/gfbgraph/gfbgraph-goa-authorizer.c
@@ -17,6 +17,16 @@
  * with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * SECTION:gfbgraph-goa-authorizer
+ * @short_description: GFBGraph GOA authorization interface
+ * @stability: Unstable
+ * @include: gfbgraph/gfbgraph.h
+ *
+ * #GFBGraphGoaAuthorizer provides an implementation of the #GFBGraphAuthorizer interface
+ * for authorization using GNOME Online Accounts (GOA).
+ **/
+
 #include "gfbgraph-authorizer.h"
 #include "gfbgraph-goa-authorizer.h"
 
@@ -65,6 +75,12 @@ gfbgraph_goa_authorizer_class_init (GFBGraphGoaAuthorizerClass *klass)
         gobject_class->set_property = gfbgraph_goa_authorizer_set_property;
         gobject_class->dispose = gfbgraph_goa_authorizer_dispose;
 
+        /**
+         * GFBGraphGoaAuthorizer:goa-object:
+         *
+         * The GOA account providing authentication.
+         *
+         **/
         g_object_class_install_property (gobject_class,
                                          PROP_GOA_OBJECT,
                                          g_param_spec_object ("goa-object",