Several fixes to the GObject Introspectionwip/tintou/gobject-introspection-fixes

7 files changed, 74 insertions, 36 deletions

diff --git a/rest/oauth-proxy.c b/rest/oauth-proxy.c
index f8c0053..04848c6 100644
--- a/rest/oauth-proxy.c
+++ b/rest/oauth-proxy.c
@@ -282,8 +282,8 @@ oauth_proxy_new_with_token (const char *consumer_key,
 /**
  * oauth_proxy_request_token:
  * @proxy: an #OAuthProxy
- * @function: the function name to invoke
- * @callback_uri: the callback URI
+ * @function: (allow-none): the function name to invoke
+ * @callback_uri: (allow-none): the callback URI or %NULL
  * @error: a #GError, or %NULL
  *
  * Perform the Request Token phase of OAuth, invoking @function (defaulting to
@@ -352,7 +352,7 @@ request_token_cb (GObject      *source_object,
  * @proxy: an #OAuthProxy
  * @function: (nullable): the function name to invoke
  * @callback_uri: (nullable): the callback URI
- * @callback: (scope async): a #OAuthProxyAuthCallback to invoke on completion
+ * @callback: (scope async): a #GAsyncReadyCallback to invoke on completion
  * @user_data: user data to pass to @callback
  *
  * Perform the Request Token phase of OAuth, invoking @function (defaulting to
@@ -485,7 +485,7 @@ access_token_cb (GObject      *source_object,
  * @proxy: an #OAuthProxy
  * @function: the function name to invoke
  * @verifier: the verifier
- * @callback: (scope async): a #OAuthProxyAuthCallback to invoke on completion
+ * @callback: (scope async): a #GAsyncReadyCallback to invoke on completion
  * @user_data: user data to pass to @callback
  *
  * Perform the Access Token phase of OAuth, invoking @function (defaulting to
diff --git a/rest/oauth2-proxy.c b/rest/oauth2-proxy.c
index 24e5da0..1530a54 100644
--- a/rest/oauth2-proxy.c
+++ b/rest/oauth2-proxy.c
@@ -260,8 +260,9 @@ append_query_param (gpointer key, gpointer value, gpointer user_data)
  * oauth2_proxy_build_login_url_full:
  * @proxy: a OAuth2Proxy object
  * @redirect_uri: the uri to redirect to after the user authenticates
- * @extra_params: any extra parameters to add to the login url (e.g. facebook
- * uses 'scope=foo,bar' to request extended permissions).
+ * @extra_params: (element-type utf8 utf8): any extra parameters to add to the
+ * login url (e.g. facebook uses 'scope=foo,bar' to request extended
+ * permissions).
  *
  * Builds a url at which the user can log in to the specified OAuth2-based web
  * service.  In general, this url should be displayed in an embedded browser
diff --git a/rest/rest-param.c b/rest/rest-param.c
index 8ad105f..cf8f822 100644
--- a/rest/rest-param.c
+++ b/rest/rest-param.c
@@ -280,7 +280,7 @@ rest_param_is_string (RestParam *param)
  * Get the content of @param.  The content should be treated as read-only and
  * not modified in any way.
  *
- * Returns: (transfer none): the content.
+ * Returns: (transfer none) (array) (element-type guint8):: the content.
  **/
 gconstpointer
 rest_param_get_content (RestParam *param)
diff --git a/rest/rest-params.c b/rest/rest-params.c
index 369215b..ef10de5 100644
--- a/rest/rest-params.c
+++ b/rest/rest-params.c
@@ -79,7 +79,7 @@ rest_params_free (RestParams *params)
 /**
  * rest_params_add:
  * @params: a valid #RestParams
- * @param: a valid #RestParam
+ * @param: (transfer full): a valid #RestParam
  *
  * Add @param to @params.
  **/
@@ -101,7 +101,8 @@ rest_params_add (RestParams *params, RestParam *param)
  *
  * Return the #RestParam called @name, or %NULL if it doesn't exist.
  *
- * Returns: a #RestParam or %NULL if the name doesn't exist
+ * Returns: (nullable) (transfer none): a #RestParam or %NULL if the name
+ * doesn't exist
  **/
 RestParam *
 rest_params_get (RestParams *params, const char *name)
@@ -170,7 +171,7 @@ rest_params_are_strings (RestParams *params)
  * The values are owned by the #RestParams, so don't destroy the #RestParams
  * before the hash table.
  *
- * Returns: (element-type utf8 Rest.Param) (transfer container): a new #GHashTable.
+ * Returns: (element-type utf8 utf8) (transfer container): a new #GHashTable.
  **/
 GHashTable *
 rest_params_as_string_hash_table (RestParams *params)
diff --git a/rest/rest-proxy-call.c b/rest/rest-proxy-call.c
index 72c8261..170a4fc 100644
--- a/rest/rest-proxy-call.c
+++ b/rest/rest-proxy-call.c
@@ -28,12 +28,39 @@
 #include "rest-private.h"
 #include "rest-proxy-call-private.h"
 
+/**
+ * RestProxyCallAsyncCallback:
+ * @call: The #RestProxyCall
+ * @error: (nullable): a #GError, %NULL when no error occured
+ * @weak_object: (nullable):
+ * @user_data:
+ **/
+
+/**
+ * RestProxyCallContinuousCallback:
+ * @call: The #RestProxyCall
+ * @buf: (array length=len) (element-type gchar): A buffer
+ * @len: The length of the buffer @buf
+ * @error: (nullable): a #GError, %NULL when no error occured
+ * @weak_object: (nullable):
+ * @user_data:
+ **/
+
+/**
+ * RestProxyCallUploadCallback:
+ * @call: The #RestProxyCall
+ * @total: the total number of bytes
+ * @uploaded: the uploaded number of bytes
+ * @error: (nullable): a #GError, %NULL when no error occured
+ * @weak_object: (nullable):
+ * @user_data:
+ **/
 
 struct _RestProxyCallAsyncClosure {
   RestProxyCall *call;
   RestProxyCallAsyncCallback callback;
   GObject *weak_object;
-  gpointer userdata;
+  gpointer user_data;
   SoupMessage *message;
 };
 typedef struct _RestProxyCallAsyncClosure RestProxyCallAsyncClosure;
@@ -42,7 +69,7 @@ struct _RestProxyCallContinuousClosure {
   RestProxyCall *call;
   RestProxyCallContinuousCallback callback;
   GObject *weak_object;
-  gpointer userdata;
+  gpointer user_data;
   SoupMessage *message;
 };
 typedef struct _RestProxyCallContinuousClosure RestProxyCallContinuousClosure;
@@ -51,7 +78,7 @@ struct _RestProxyCallUploadClosure {
   RestProxyCall *call;
   RestProxyCallUploadCallback callback;
   GObject *weak_object;
-  gpointer userdata;
+  gpointer user_data;
   SoupMessage *message;
   gsize uploaded;
 };
@@ -414,6 +441,15 @@ rest_proxy_call_add_param (RestProxyCall *call,
   rest_params_add (priv->params, param);
 }
 
+/**
+ * rest_proxy_call_add_param_full:
+ * @call: The #RestProxyCall
+ * @param: (transfer full): The #RestParam to add
+ *
+ * Add a query parameter called @param with the string 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_full (RestProxyCall *call, RestParam *param)
 {
@@ -529,9 +565,9 @@ static void _call_async_weak_notify_cb (gpointer *data,
 static void
 _populate_headers_hash_table (const gchar *name,
                               const gchar *value,
-                              gpointer     userdata)
+                              gpointer     user_data)
 {
-  GHashTable *headers = (GHashTable *)userdata;
+  GHashTable *headers = (GHashTable *)user_data;
 
   g_hash_table_insert (headers, g_strdup (name), g_strdup (value));
 }
@@ -612,14 +648,14 @@ finish_call (RestProxyCall *call, SoupMessage *message, GError **error)
 static void
 _continuous_call_message_completed_cb (SoupSession *session,
                                        SoupMessage *message,
-                                       gpointer     userdata)
+                                       gpointer     user_data)
 {
   RestProxyCallContinuousClosure *closure;
   RestProxyCall *call;
   RestProxyCallPrivate *priv;
   GError *error = NULL;
 
-  closure = (RestProxyCallContinuousClosure *)userdata;
+  closure = (RestProxyCallContinuousClosure *)user_data;
   call = closure->call;
   priv = GET_PRIVATE (call);
 
@@ -633,7 +669,7 @@ _continuous_call_message_completed_cb (SoupSession *session,
                      0,
                      error,
                      closure->weak_object,
-                     closure->userdata);
+                     closure->user_data);
 
   g_clear_error (&error);
 
@@ -961,7 +997,7 @@ _continuous_call_message_got_chunk_cb (SoupMessage                    *msg,
                      chunk->length,
                      NULL,
                      closure->weak_object,
-                     closure->userdata);
+                     closure->user_data);
 }
 
 
@@ -970,7 +1006,7 @@ _continuous_call_message_got_chunk_cb (SoupMessage                    *msg,
  * @call: The #RestProxyCall
  * @callback: a #RestProxyCallContinuousCallback to invoke when data is available
  * @weak_object: The #GObject to weakly reference and tie the lifecycle to
- * @userdata: (closure): data to pass to @callback
+ * @user_data: (closure): data to pass to @callback
  * @error: (out) (allow-none): a #GError, or %NULL
  *
  * Asynchronously invoke @call but expect a continuous stream of content. This
@@ -991,7 +1027,7 @@ gboolean
 rest_proxy_call_continuous (RestProxyCall                    *call,
                             RestProxyCallContinuousCallback   callback,
                             GObject                          *weak_object,
-                            gpointer                          userdata,
+                            gpointer                          user_data,
                             GError                          **error)
 {
   RestProxyCallPrivate *priv = GET_PRIVATE (call);
@@ -1019,7 +1055,7 @@ rest_proxy_call_continuous (RestProxyCall                    *call,
   closure->callback = callback;
   closure->weak_object = weak_object;
   closure->message = message;
-  closure->userdata = userdata;
+  closure->user_data = user_data;
 
   priv->cur_call_closure = (RestProxyCallAsyncClosure *)closure;
 
@@ -1064,7 +1100,7 @@ _upload_call_message_completed_cb (SoupSession *session,
                      closure->uploaded,
                      error,
                      closure->weak_object,
-                     closure->userdata);
+                     closure->user_data);
 
   g_clear_error (&error);
 
@@ -1094,7 +1130,7 @@ _upload_call_message_wrote_data_cb (SoupMessage                *msg,
                        closure->uploaded,
                        NULL,
                        closure->weak_object,
-                       closure->userdata);
+                       closure->user_data);
 }
 
 /**
@@ -1103,7 +1139,7 @@ _upload_call_message_wrote_data_cb (SoupMessage                *msg,
  * @callback: (scope async): a #RestProxyCallUploadCallback to invoke when a chunk
  *   of data was uploaded
  * @weak_object: The #GObject to weakly reference and tie the lifecycle to
- * @userdata: data to pass to @callback
+ * @user_data: data to pass to @callback
  * @error: a #GError, or %NULL
  *
  * Asynchronously invoke @call but expect to have the callback invoked every time a
@@ -1123,7 +1159,7 @@ gboolean
 rest_proxy_call_upload (RestProxyCall                *call,
                         RestProxyCallUploadCallback   callback,
                         GObject                      *weak_object,
-                        gpointer                      userdata,
+                        gpointer                      user_data,
                         GError                      **error)
 {
   RestProxyCallPrivate *priv = GET_PRIVATE (call);
@@ -1148,7 +1184,7 @@ rest_proxy_call_upload (RestProxyCall                *call,
   closure->callback = callback;
   closure->weak_object = weak_object;
   closure->message = message;
-  closure->userdata = userdata;
+  closure->user_data = user_data;
   closure->uploaded = 0;
 
   priv->cur_call_closure = (RestProxyCallAsyncClosure *)closure;
@@ -1274,8 +1310,8 @@ rest_proxy_call_lookup_response_header (RestProxyCall *call,
  * rest_proxy_call_get_response_headers:
  * @call: The #RestProxyCall
  *
- * Returns: (transfer container): pointer to a hash table of
- * headers. This hash table must not be changed. You should call
+ * Returns: (transfer container) (element-type utf8 utf8): pointer to a
+ * hash table of headers. This hash table must not be changed. You should call
  * g_hash_table_unref() when you have finished with it.
  */
 GHashTable *
@@ -1361,7 +1397,7 @@ rest_proxy_call_get_status_message (RestProxyCall *call)
  * rest_proxy_call_serialize_params:
  * @call: The #RestProxyCall
  * @content_type: (out): Content type of the payload
- * @content: (out): The payload
+ * @content: (out) (array length=content_len) (element-type gchar): The payload
  * @content_len: (out): Length of the payload data
  * @error: a #GError, or %NULL
  *
diff --git a/rest/rest-proxy-call.h b/rest/rest-proxy-call.h
index 53077f7..07f5db7 100644
--- a/rest/rest-proxy-call.h
+++ b/rest/rest-proxy-call.h
@@ -131,7 +131,7 @@ RestParams *rest_proxy_call_get_params (RestProxyCall *call);
 typedef void (*RestProxyCallAsyncCallback)(RestProxyCall *call,
                                            const GError  *error,
                                            GObject       *weak_object,
-                                           gpointer       userdata);
+                                           gpointer       user_data);
 
 void rest_proxy_call_invoke_async (RestProxyCall       *call,
                                    GCancellable        *cancellable,
@@ -147,12 +147,12 @@ typedef void (*RestProxyCallContinuousCallback) (RestProxyCall *call,
                                                  gsize          len,
                                                  const GError  *error,
                                                  GObject       *weak_object,
-                                                 gpointer       userdata);
+                                                 gpointer       user_data);
 
 gboolean rest_proxy_call_continuous (RestProxyCall                    *call,
                                      RestProxyCallContinuousCallback   callback,
                                      GObject                          *weak_object,
-                                     gpointer                          userdata,
+                                     gpointer                          user_data,
                                      GError                          **error);
 
 typedef void (*RestProxyCallUploadCallback) (RestProxyCall *call,
@@ -160,12 +160,12 @@ typedef void (*RestProxyCallUploadCallback) (RestProxyCall *call,
                                              gsize          uploaded,
                                              const GError  *error,
                                              GObject       *weak_object,
-                                             gpointer       userdata);
+                                             gpointer       user_data);
 
 gboolean rest_proxy_call_upload (RestProxyCall                *call,
                                  RestProxyCallUploadCallback   callback,
                                  GObject                      *weak_object,
-                                 gpointer                      userdata,
+                                 gpointer                      user_data,
                                  GError                      **error);
 
 gboolean rest_proxy_call_cancel (RestProxyCall *call);
diff --git a/rest/rest-xml-parser.c b/rest/rest-xml-parser.c
index 796052e..2967684 100644
--- a/rest/rest-xml-parser.c
+++ b/rest/rest-xml-parser.c
@@ -65,7 +65,7 @@ rest_xml_parser_new (void)
 /**
  * rest_xml_parser_parse_from_data:
  * @parser: a #RestXmlParser
- * @data: the XML content to parse
+ * @data: (array length=len) (element-type gchar): the XML content to parse
  * @len: the length of @data, or -1 if @data is a nul-terminated string
  *
  * Parse the XML in @data, and return a new #RestXmlNode.  If @data is invalid