From f85909fb65635b8321d1abf60c073ae854acae5e Mon Sep 17 00:00:00 2001
From: Pavel Holejsovsky <pholejs@src.gnome.org>
Date: Fri, 7 Jan 2011 09:38:35 +0100
Subject: [PATCH] Add and update GI annotations in 'Settings'

'Settings' GIO group contains GSettings and GSettingsBackend.
---
 gio/gsettings.c        | 18 +++++++++---------
 gio/gsettings.h        |  5 +++--
 gio/gsettingsbackend.c | 12 +++++++-----
 3 files changed, 19 insertions(+), 16 deletions(-)

diff --git a/gio/gsettings.c b/gio/gsettings.c
index 23164b5c7..943fc48b9 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -567,7 +567,8 @@ g_settings_class_init (GSettingsClass *class)
   /**
    * GSettings::change-event:
    * @settings: the object on which the signal was emitted
-   * @keys: an array of #GQuark<!-- -->s for the changed keys, or %NULL
+   * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
+   *        an array of #GQuark<!-- -->s for the changed keys, or %NULL
    * @n_keys: the length of the @keys array, or 0
    * @returns: %TRUE to stop other handlers from being invoked for the
    *           event. FALSE to propagate the event further.
@@ -1602,8 +1603,8 @@ g_settings_set (GSettings   *settings,
  * g_settings_get_mapped:
  * @settings: a #GSettings object
  * @key: the key to get the value for
- * @mapping: the function to map the value in the settings database to
- *           the value used by the application
+ * @mapping: (scope call): the function to map the value in the
+ *           settings database to the value used by the application
  * @user_data: user data for @mapping
  * @returns: (transfer full): the result, which may be %NULL
  *
@@ -1901,16 +1902,15 @@ g_settings_set_boolean (GSettings  *settings,
  * g_settings_get_strv:
  * @settings: a #GSettings object
  * @key: the key to get the value for
- * @returns: a newly-allocated, %NULL-terminated array of strings
+ * @returns: (array zero-terminated=1) (transfer full): a
+ * newly-allocated, %NULL-terminated array of strings, the value that
+ * is stored at @key in @settings.
  *
  * A convenience variant of g_settings_get() for string arrays.
  *
  * It is a programmer error to give a @key that isn't specified as
  * having an array of strings type in the schema for @settings.
  *
- * Returns: (array zero-terminated=1) (transfer full): the value that is
- * stored at @key in @settings.
- *
  * Since: 2.26
  */
 gchar **
@@ -2135,7 +2135,7 @@ g_settings_is_writable (GSettings   *settings,
  * @returns: (transfer full): a 'child' settings object
  *
  * Creates a 'child' settings object which has a base path of
- * <replaceable>base-path</replaceable>/@name", where
+ * <replaceable>base-path</replaceable>/@name, where
  * <replaceable>base-path</replaceable> is the base path of @settings.
  *
  * The schema for the child settings object must have been declared
@@ -2625,7 +2625,7 @@ g_settings_bind (GSettings          *settings,
 }
 
 /**
- * g_settings_bind_with_mapping:
+ * g_settings_bind_with_mapping: (skip)
  * @settings: a #GSettings object
  * @key: the key to bind
  * @object: (type GObject.Object): a #GObject
diff --git a/gio/gsettings.h b/gio/gsettings.h
index 8226750cc..324ad362d 100644
--- a/gio/gsettings.h
+++ b/gio/gsettings.h
@@ -185,8 +185,9 @@ typedef gboolean      (*GSettingsBindGetMapping)                        (GValue
 /**
  * GSettingsGetMapping:
  * @value: the #GVariant to map, or %NULL
- * @result: the result of the mapping
- * @user_data: the user data that was passed to g_settings_get_mapped()
+ * @result: (out): the result of the mapping
+ * @user_data: (closure): the user data that was passed to
+ * g_settings_get_mapped()
  * @returns: %TRUE if the conversion succeeded, %FALSE in case of an error
  *
  * The type of the function that is used to convert from a value stored
diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c
index 029e826ba..24a6f9aa1 100644
--- a/gio/gsettingsbackend.c
+++ b/gio/gsettingsbackend.c
@@ -401,7 +401,7 @@ g_settings_backend_changed (GSettingsBackend *backend,
  * g_settings_backend_keys_changed:
  * @backend: a #GSettingsBackend implementation
  * @path: the path containing the changes
- * @items: the %NULL-terminated list of changed keys
+ * @items: (array zero-terminated=1): the %NULL-terminated list of changed keys
  * @origin_tag: the origin tag
  *
  * Signals that a list of keys have possibly changed.  Backend
@@ -609,9 +609,11 @@ g_settings_backend_flatten_one (gpointer key,
 /**
  * g_settings_backend_flatten_tree:
  * @tree: a #GTree containing the changes
- * @path: the location to save the path
- * @keys: the location to save the relative keys
- * @values: the location to save the values, or %NULL
+ * @path: (out): the location to save the path
+ * @keys: (out) (transfer container) (array zero-terminated=1): the
+ *        location to save the relative keys
+ * @values: (out) (allow-none) (transfer container) (array zero-terminated=1):
+ *          the location to save the values, or %NULL
  *
  * Calculate the longest common prefix of all keys in a tree and write
  * out an array of the key names relative to that prefix and,
@@ -926,7 +928,7 @@ g_settings_backend_create_tree (void)
 
 /**
  * g_settings_backend_get_default:
- * @returns: the default #GSettingsBackend
+ * @returns: (transfer full): the default #GSettingsBackend
  *
  * Returns the default #GSettingsBackend. It is possible to override
  * the default by setting the <envar>GSETTINGS_BACKEND</envar>