Merge branch 'master' into oauth

5 files changed, 96 insertions, 0 deletions

diff --git a/docs/reference/rest/rest-sections.txt b/docs/reference/rest/rest-sections.txt
index 65ee42d..afdecb6 100644
--- a/docs/reference/rest/rest-sections.txt
+++ b/docs/reference/rest/rest-sections.txt
@@ -2,6 +2,7 @@
 <FILE>rest-proxy</FILE>
 <TITLE>RestProxy</TITLE>
 RestProxy
+RestProxyClass
 RestProxyCallRawCallback
 rest_proxy_new
 rest_proxy_bind
@@ -24,6 +25,7 @@ REST_PROXY_GET_CLASS
 <FILE>rest-proxy-call</FILE>
 <TITLE>RestProxyCall</TITLE>
 RestProxyCall
+RestProxyCallClass
 rest_proxy_call_set_method
 rest_proxy_call_add_header
 rest_proxy_call_add_headers
@@ -37,6 +39,7 @@ rest_proxy_call_add_params_from_valist
 rest_proxy_call_add_params_from_hash
 rest_proxy_call_lookup_param
 rest_proxy_call_remove_param
+rest_proxy_call_get_params
 rest_proxy_call_run
 RestProxyCallAsyncCallback
 rest_proxy_call_async
diff --git a/rest/rest-proxy-call.c b/rest/rest-proxy-call.c
index 7b91d76..d435b7b 100644
--- a/rest/rest-proxy-call.c
+++ b/rest/rest-proxy-call.c
@@ -156,6 +156,13 @@ rest_proxy_call_init (RestProxyCall *self)
                                                   g_free);
 }
 
+/**
+ * rest_proxy_call_set_method:
+ * @call: The #RestProxyCall
+ * @method: The HTTP method to use
+ *
+ * Set the HTTP method to use when making the call, for example GET or POST.
+ */
 void 
 rest_proxy_call_set_method (RestProxyCall *call,
                             const gchar   *method)
@@ -238,6 +245,15 @@ rest_proxy_call_remove_header (RestProxyCall *call,
   g_hash_table_remove (priv->headers, header);
 }
 
+/**
+ * rest_proxy_call_add_param:
+ * @call: The #RestProxyCall
+ * @param: The name of the parameter to set
+ * @value: The value of the parameter
+ *
+ * Add a query parameter called @param with the value %value to the call.  If a
+ * parameter with this name already exists, the new value will replace the old.
+ */
 void 
 rest_proxy_call_add_param (RestProxyCall *call,
                            const gchar   *param,
@@ -251,6 +267,14 @@ rest_proxy_call_add_param (RestProxyCall *call,
 
 }
 
+/**
+ * rest_proxy_call_add_params:
+ * @call: The #RestProxyCall
+ * @Varargs: Parameter name and value pairs, followed by %NULL.
+ *
+ * Add the specified parameter name and value pairs to the call.  If a parameter
+ * already exists, the new value will replace the old.
+ */
 void
 rest_proxy_call_add_params (RestProxyCall *call,
                             ...)
@@ -262,6 +286,14 @@ rest_proxy_call_add_params (RestProxyCall *call,
   va_end (params);
 }
 
+/**
+ * rest_proxy_call_add_params_from_valist:
+ * @call: The #RestProxyCall
+ * @params: Parameter name and value pairs, followed by %NULL.
+ *
+ * Add the specified parameter name and value pairs to the call.  If a parameter
+ * already exists, the new value will replace the old.
+ */
 void 
 rest_proxy_call_add_params_from_valist (RestProxyCall *call,
                                         va_list        params)
@@ -276,6 +308,16 @@ rest_proxy_call_add_params_from_valist (RestProxyCall *call,
   }
 }
 
+/**
+ * rest_proxy_call_lookup_param:
+ * @call: The #RestProxyCall
+ * @param: The paramter name
+ *
+ * Get the value of the parameter called @name.
+ *
+ * Returns: The parameter value, or %NULL if it does not exist. This string is
+ * owned by the #RestProxyCall and should not be freed.
+ */
 const gchar *
 rest_proxy_call_lookup_param (RestProxyCall *call,
                               const gchar   *param)
@@ -285,6 +327,13 @@ rest_proxy_call_lookup_param (RestProxyCall *call,
   return g_hash_table_lookup (priv->params, param);
 }
 
+/**
+ * rest_proxy_call_remove_param:
+ * @call: The #RestProxyCall
+ * @param: The paramter name
+ *
+ * Remove the parameter named @param from the call.
+ */
 void 
 rest_proxy_call_remove_param (RestProxyCall *call,
                               const gchar   *param)
@@ -294,6 +343,15 @@ rest_proxy_call_remove_param (RestProxyCall *call,
   g_hash_table_remove (priv->params, param);
 }
 
+/**
+ * rest_proxy_call_get_params:
+ * @call: The #RestProxyCall
+ *
+ * Get the parameters as a #GHashTable of parameter names to values.  The caller
+ * should call g_hash_table_unref() when they have finished using it.
+ *
+ * Returns: A #GHashTable.
+ */
 GHashTable *
 rest_proxy_call_get_params (RestProxyCall *call)
 {
diff --git a/rest/rest-proxy-call.h b/rest/rest-proxy-call.h
index 113eccc..8725b67 100644
--- a/rest/rest-proxy-call.h
+++ b/rest/rest-proxy-call.h
@@ -22,12 +22,26 @@ G_BEGIN_DECLS
 #define REST_PROXY_CALL_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), REST_TYPE_PROXY_CALL, RestProxyCallClass))
 
+/**
+ * RestProxyCall:
+ *
+ * #RestProxyCall has no publicly available members.
+ */
 typedef struct {
   GObject parent;
 } RestProxyCall;
 
+/**
+ * RestProxyCallClass:
+ * @prepare: Virtual function called before making the request, This allows the
+ * call to be modified, for example to add a signature.
+ *
+ * Class structure for #RestProxy.
+ */
 typedef struct {
+  /*< private >*/
   GObjectClass parent_class;
+  /*< public >*/
   gboolean (*prepare)(RestProxyCall *call, GError **error);
 } RestProxyCallClass;
 
@@ -41,6 +55,7 @@ void rest_proxy_call_add_header (RestProxyCall *call,
                                  const gchar   *header,
                                  const gchar   *value);
 
+G_GNUC_NULL_TERMINATED
 void rest_proxy_call_add_headers (RestProxyCall *call,
                                   const char    *first_header_name,
                                   ...);
@@ -61,6 +76,7 @@ void rest_proxy_call_add_param (RestProxyCall *call,
                                 const gchar   *param,
                                 const gchar   *value);
 
+G_GNUC_NULL_TERMINATED
 void rest_proxy_call_add_params (RestProxyCall *call,
                                  ...);
 
diff --git a/rest/rest-proxy.c b/rest/rest-proxy.c
index a42fd22..26b0449 100644
--- a/rest/rest-proxy.c
+++ b/rest/rest-proxy.c
@@ -164,6 +164,20 @@ rest_proxy_init (RestProxy *self)
   priv->session = soup_session_async_new ();
 }
 
+/**
+ * rest_proxy_new:
+ * @url_format: the endpoint URL
+ * @binding_required: whether the URL needs to be bound before calling
+ *
+ * Create a new #RestProxy for the specified endpoint @url_format, using the
+ * %GET method.
+ *
+ * Set @binding_required to %TRUE if the URL contains string formatting
+ * operations (for example "http://foo.com/%<!-- -->s".  These must be expanded
+ * using rest_proxy_bind() before invoking the proxy.
+ *
+ * Returns: A new #RestProxy.
+ */
 RestProxy *
 rest_proxy_new (const gchar *url_format, 
                 gboolean     binding_required)
diff --git a/rest/rest-proxy.h b/rest/rest-proxy.h
index 9862cb1..5f00f8b 100644
--- a/rest/rest-proxy.h
+++ b/rest/rest-proxy.h
@@ -23,6 +23,11 @@ G_BEGIN_DECLS
 #define REST_PROXY_GET_CLASS(obj) \
   (G_TYPE_INSTANCE_GET_CLASS ((obj), REST_TYPE_PROXY, RestProxyClass))
 
+/**
+ * RestProxy:
+ *
+ * #RestProxy has no publicly available members.
+ */
 typedef struct {
   GObject parent;
 } RestProxy;