[PATCH core 08/10] wc: gtkdoc documentation

[Víctor Manuel Jáquez Leal <vjaquez igalia com>]

Signed-off-by: Víctor Manuel Jáquez Leal <vjaquez igalia com>
---
 libs/net/grl-net-wc.c |   77 +++++++++++++++++++++++++++++++++++++++++++++++++
 libs/net/grl-net-wc.h |   23 ++++++++++++++
 2 files changed, 100 insertions(+), 0 deletions(-)

diff --git a/libs/net/grl-net-wc.c b/libs/net/grl-net-wc.c
index 0d45e66..c4ce7d0 100644
--- a/libs/net/grl-net-wc.c
+++ b/libs/net/grl-net-wc.c
@@ -22,6 +22,15 @@
  *
  */
 
+/**
+ * SECTION:grl-net-wc
+ * @short_description: small and simple HTTP client
+ *
+ * Most of the Grilo's sources need to access to web resources. The purpose of
+ * this utility class is to provide an thin and lean mechanism for those plugins
+ * to interact with those resources.
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif
@@ -93,6 +102,11 @@ grl_net_wc_class_init (GrlNetWcClass *klass)
 
   g_type_class_add_private (klass, sizeof (GrlNetWcPrivate));
 
+  /**
+   * GrlNetWc::loglevel
+   *
+   * The log lever for HTTP connections. This value is used by libsoup.
+   */
   g_object_class_install_property (g_klass,
                                    PROP_LOG_LEVEL,
                                    g_param_spec_uint ("loglevel",
@@ -102,6 +116,12 @@ grl_net_wc_class_init (GrlNetWcClass *klass)
                                                       G_PARAM_READWRITE |
                                                       G_PARAM_STATIC_STRINGS));
 
+  /**
+   * GrlNetWc::throttling
+   *
+   * The timeout in seconds between connections. All the connections will be
+   * queued and each one will be dispatched after waiting this value.
+   */
   g_object_class_install_property (g_klass,
                                    PROP_THROTTLING,
                                    g_param_spec_uint ("throttling",
@@ -382,12 +402,29 @@ get_url (GrlNetWc *self,
   }
 }
 
+/**
+ * grl_net_wc_new:
+ *
+ * Returns: (element-type Grl.NetWc): a new allocated instance of #GrlNetWc.
+ * Do g_object_unref() after use it.
+ */
 GrlNetWc *
 grl_net_wc_new (void)
 {
   return g_object_new (GRL_TYPE_NET_WC, NULL);
 }
 
+/**
+ * grl_net_wc_request_async:
+ * @self: a #GrlNetWc instance
+ * @uri: The URI of the resource to request
+ * @cancellable: (allow-none): a #GCancellable instance or %NULL to ignore
+ * @callback: The callback when the result is ready
+ * @user_data: User data set for the @callback
+ *
+ * Request the fetching of a web resource given the @uri. This request is
+ * asynchronous, thus the result will be returned within the @callback.
+ */
 void
 grl_net_wc_request_async (GrlNetWc *self,
                           const char *uri,
@@ -405,6 +442,24 @@ grl_net_wc_request_async (GrlNetWc *self,
   get_url (self, uri, G_ASYNC_RESULT (result), cancellable);
 }
 
+/**
+ * grl_net_wc_request_finish:
+ * @self: a #GrlNetWc instance
+ * @result: The result of the request
+ * @content: The contents of the resource
+ * @length: (allow-none): The length of the contents or %NULL if it is not
+ * needed
+ * @error: return location for a #GError, or %NULL
+ *
+ * Finishes an asynchronous load of the file's contents.
+ * The contents are placed in contents, and length is set to the size of the
+ * contents string.
+ *
+ * The content address will be invalidated at the next request. So if you
+ * want to keep it, please copy it into another address.
+ *
+ * Returns: %TRUE if the request was successfull. If %FALSE a error occurred.
+ */
 gboolean
 grl_net_wc_request_finish (GrlNetWc *self,
                            GAsyncResult *result,
@@ -437,6 +492,14 @@ end_func:
   return ret;
 }
 
+/**
+ * grl_net_wc_set_log_level:
+ * @self: a #GrlNetWc instance
+ * @log_level: the libsoup log level to set [0,3]
+ *
+ * Setting the log level the logger feature is added into
+ * the libsoup session.
+ */
 void
 grl_net_wc_set_log_level (GrlNetWc *self,
                           guint log_level)
@@ -458,6 +521,14 @@ grl_net_wc_set_log_level (GrlNetWc *self,
   self->priv->log_level = (SoupLoggerLogLevel) log_level;
 }
 
+/**
+ * grl_net_wc_set_throttling:
+ * @self: a #GrlNetWc instance
+ * @throttling: the number of seconds to wait between requests
+ *
+ * Setting this property, the #GrlNetWc will queue all the requests and
+ * will dispatch them with a pause between them of this value.
+ */
 void
 grl_net_wc_set_throttling (GrlNetWc *self,
                            guint throttling)
@@ -477,6 +548,12 @@ grl_net_wc_set_throttling (GrlNetWc *self,
   self->priv->throttling = throttling;
 }
 
+/**
+ * grl_net_wc_flush_delayed_requests:
+ * @self: a #GrlNetWc instance
+ *
+ * This method will flush all the pending request in the queue.
+ */
 void
 grl_net_wc_flush_delayed_requests (GrlNetWc *self)
 {
diff --git a/libs/net/grl-net-wc.h b/libs/net/grl-net-wc.h
index 9f9ad9a..38dd84b 100644
--- a/libs/net/grl-net-wc.h
+++ b/libs/net/grl-net-wc.h
@@ -29,6 +29,21 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GrlNetWcError:
+ * @GRL_NET_WC_ERROR_UNAVAILABLE: TBD
+ * @GRL_NET_WC_ERROR_PROTOCOL_ERROR: Invalid URI or header
+ * @GRL_NET_WC_ERROR_AUTHENTICATION_REQUIRED: Required authentication
+ * @GRL_NET_WC_ERROR_NOT_FOUND: Request resource not found
+ * @GRL_NET_WC_ERROR_CONFLICT: The entry has been modified since is was
+ * downloaded
+ * @GRL_NET_WC_ERROR_FORBIDDEN: TBD
+ * @GRL_NET_WC_ERROR_NETWORK_ERROR: Cannot connect to the server
+ * @GRL_NET_WC_ERROR_PROXY_ERROR: Cannot connect to the proxy server
+ *
+ * These constants identify all the available errors managed by
+ * the web client.
+ */
 typedef enum {
 	GRL_NET_WC_ERROR_UNAVAILABLE = 1,
 	GRL_NET_WC_ERROR_PROTOCOL_ERROR,
@@ -74,6 +89,14 @@ struct _GrlNetWc {
 
 typedef struct _GrlNetWcClass GrlNetWcClass;
 
+/**
+ * GrlNetWcClass:
+ * @parent_class: the parent class structure
+ *
+ * Grilo web client helper class.
+ *
+ * It's a simple a thin web client for be used by the sources.
+ */
 struct _GrlNetWcClass {
 
   GObjectClass parent_class;
-- 
1.7.1