[gconf] introspection: Add annotations to fix warnings

[Owen Taylor <otaylor src gnome org>]

commit b444c90d281ca33d87d4a1c6b8062ef7103ef0e8
Author: Owen W. Taylor <otaylor fishsoup net>
Date:   Tue Sep 7 16:05:32 2010 -0400

    introspection: Add annotations to fix warnings
    
    Add (skip) (transfer) and (element-type) annotations to fix
    almost all warnings from introspection (there is one bug left in
    the scanner causing a warning about GConfError.)
    
    Docs for the functions being annotated are moved to the source files.
    
    All types that are not currently boxed or GObject are skipped; some
    of these could be made boxed with only a small amount of work.

 doc/gconf/tmpl/gconf-changeset.sgml |   27 +++----
 doc/gconf/tmpl/gconf-client.sgml    |  121 +++++-------------------------
 doc/gconf/tmpl/gconf-engine.sgml    |   12 +--
 doc/gconf/tmpl/gconf-listeners.sgml |    6 +-
 doc/gconf/tmpl/gconf-schema.sgml    |    2 +-
 doc/gconf/tmpl/gconf-value.sgml     |   10 +--
 doc/gconf/tmpl/gconf.sgml           |  133 +++++++--------------------------
 gconf/gconf-changeset.c             |   29 +++++++
 gconf/gconf-client.c                |  127 +++++++++++++++++++++++++++++++
 gconf/gconf-engine.h                |    7 ++
 gconf/gconf-listeners.h             |   11 +++
 gconf/gconf-schema.h                |    7 ++
 gconf/gconf-value.c                 |   12 +++
 gconf/gconf-value.h                 |    5 +
 gconf/gconf.c                       |  141 +++++++++++++++++++++++++++++++++++
 15 files changed, 408 insertions(+), 242 deletions(-)
---
diff --git a/doc/gconf/tmpl/gconf-changeset.sgml b/doc/gconf/tmpl/gconf-changeset.sgml
index df1bec8..af33f9a 100644
--- a/doc/gconf/tmpl/gconf-changeset.sgml
+++ b/doc/gconf/tmpl/gconf-changeset.sgml
@@ -178,16 +178,12 @@ If @key is not in the change set, this function has no effect.
 
 <!-- ##### FUNCTION gconf_change_set_foreach ##### -->
 <para>
-Iterates over a #GConfChangeSet by calling a
-#GConfChangeSetForeachFunc for each change in the set. See the
-description of #GConfChangeSetForeachFunc for details.  You may not
-call gconf_change_set_remove() during the iteration, because you'll
-confuse the internal data structures and cause memory corruption.
+
 </para>
 
- cs: a #GConfChangeSet.
- func: function to call for each change in the change set.
- user_data: user data to pass to the #GConfChangeSetForeachFunc.
+ cs: 
+ func: 
+ user_data: 
 
 
 <!-- ##### FUNCTION gconf_change_set_check_value ##### -->
@@ -323,21 +319,20 @@ the pair of values being set for the key.
 
 <!-- ##### FUNCTION gconf_change_set_set_user_data ##### -->
 <para>
-Sets the user_data and the destroy notification function fields of the 
-#GConfChangeSet.
+
 </para>
 
- cs: a #GConfChangeSet.
- data: a #gpointer.
- dnotify: a pointer to the function to be called during destroy.
+ cs: 
+ data: 
+ dnotify: 
 
 
 <!-- ##### FUNCTION gconf_change_set_get_user_data ##### -->
 <para>
-Returns the user_data field of the #GConfChangeSet.
+
 </para>
 
- cs: a #GConfChangeSet.
- Returns: a pointer to the user_data.
+ cs: 
+ Returns: 
 
 
diff --git a/doc/gconf/tmpl/gconf-client.sgml b/doc/gconf/tmpl/gconf-client.sgml
index 43aeb49..1dc1907 100644
--- a/doc/gconf/tmpl/gconf-client.sgml
+++ b/doc/gconf/tmpl/gconf-client.sgml
@@ -191,31 +191,20 @@ Casts a pointer to a #GConfClient*.
 
 <!-- ##### FUNCTION gconf_client_get_default ##### -->
 <para>
-Creates a new #GConfClient using the default #GConfEngine. Normally this is the
-engine you want. If someone else is already using the default
-#GConfClient, this function returns the same one they're using, but 
-with the reference count incremented. So you have to unref either way.
-</para>
 
-<para>
-It's important to call g_type_init() before using this GObject, to initialize the type system.
 </para>
 
 @void: 
- Returns: a new #GConfClient. g_object_unref() when you're done.
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_client_get_for_engine ##### -->
 <para>
-Creates a new #GConfClient with a specific #GConfEngine. Only specialized
-configuration-related programs should need to call this function. The
-returned #GConfClient should be unref'd when you're done with g_object_unref().
-Remember to avoid using the #GConfEngine directly once you have a #GConfClient
-wrapper.
+
 </para>
 
- engine: the #GConfEngine to use.
- Returns: a new #GConfClient.
+ engine: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_client_add_dir ##### -->
@@ -329,11 +318,10 @@ Controls the default error handling for #GConfClient. See
 
 <!-- ##### FUNCTION gconf_client_set_global_default_error_handler ##### -->
 <para>
-Set @func as the default error handler for the #GConfClient. This handler would be called
-for all #GConfClient internal errors.
+
 </para>
 
- func: pointer to the function to be called for error handling.
+ func: 
 
 
 <!-- ##### FUNCTION gconf_client_clear_cache ##### -->
@@ -456,32 +444,24 @@ but uses #GConfClient caching and error-handling features.
 
 <!-- ##### FUNCTION gconf_client_all_entries ##### -->
 <para>
-Lists the key-value pairs in @dir. Does not list subdirectories; for
-that use gconf_client_all_dirs(). The returned list contains #GConfEntry
-objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key
-and a value. The list is not recursive, it contains only the immediate
-children of @dir.  To free the returned list, gconf_entry_free()
-each list element, then g_slist_free() the list itself.
-Just like gconf_engine_all_entries (), but uses #GConfClient caching and error-handling features.
+
 </para>
 
- client: a #GConfClient.
- dir: directory to list.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: List of #GConfEntry.
+ client: 
+ dir: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_client_all_dirs ##### -->
 <para>
-Lists the subdirectories in @dir. The returned list contains allocated
-strings. Each string is the absolute path of a subdirectory. You should g_free() each string in the list, then g_slist_free() the list itself.
-Just like gconf_engine_all_dirs (), but uses #GConfClient caching and error-handling features.
+
 </para>
 
- client: a #GConfClient.
- dir: directory to get subdirectories from.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: List of allocated subdirectory names.
+ client: 
+ dir: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_client_suggest_sync ##### -->
@@ -601,73 +581,14 @@ Just like gconf_engine_get_schema (), but uses #GConfClient caching and error-ha
 
 <!-- ##### FUNCTION gconf_client_get_list ##### -->
 <para>
-Requests the list (%GCONF_VALUE_LIST) stored at @key.  Automatically
-performs type-checking, so if a non-list is stored at @key, or the
-list does not contain elements of type @list_type, an error is
-returned. If no value is set or an error occurs, <symbol>NULL</symbol>
-is returned. Note that <symbol>NULL</symbol> is also the empty list,
-so if you need to distinguish the empty list from an unset value, you
-must use gconf_client_get () to obtain a raw #GConfValue.
-</para>
-
-<para>
-<emphasis>Remember that GConf lists can only store primitive types:
-%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
-%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember
-that lists must be uniform, you may not mix types in the same list.
-</para>
-
-<para>
-The type of the list elements depends on @list_type. A #GConfValue
-with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue
-objects. gconf_client_get_list() automatically converts to primitive C
-types. Thus, the list-&gt;data fields in the returned list 
-contain:
- 
-<informaltable pgwide="1" frame="none">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>%GCONF_VALUE_INT</entry>
-<entry>The integer itself, converted with GINT_TO_POINTER()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_BOOL</entry>
-<entry>The bool itself, converted with GINT_TO_POINTER()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_FLOAT</entry>
-<entry>A pointer to #gdouble, which should be freed with g_free()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_STRING</entry>
-<entry>A pointer to #gchar, which should be freed with g_free()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_SCHEMA</entry>
-<entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-
-In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must
-g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must
-gconf_schema_free() each element. In all cases you must free the
-list itself with g_slist_free().
 
-Just like gconf_engine_get_list (), but uses #GConfClient caching and error-handling features.
 </para>
 
- client: a #GConfClient.
- key: key you want the value of.
- list_type: type of each list element.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: an allocated list, with elements as described above.
+ client: 
+ key: 
+ list_type: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_client_get_pair ##### -->
diff --git a/doc/gconf/tmpl/gconf-engine.sgml b/doc/gconf/tmpl/gconf-engine.sgml
index adff916..92fce0a 100644
--- a/doc/gconf/tmpl/gconf-engine.sgml
+++ b/doc/gconf/tmpl/gconf-engine.sgml
@@ -33,23 +33,17 @@ configuration values.
 
 <!-- ##### STRUCT GConfEngine ##### -->
 <para>
-An opaque data type representing one or more configuration sources.
+
 </para>
 
 
 <!-- ##### FUNCTION gconf_engine_get_default ##### -->
 <para>
-Returns the default #GConfEngine. All clients should use this, unless 
-they are special configuration-related tools. The caller of this
-function assumes one reference count, and must call
-gconf_engine_unref() at some point. It's fairly important to unref the
-#GConfEngine, to cleanly close the connection to
-<application>gconfd</application>. So if possible close the connection
-before exiting your application. see ? printf() <function>printf()</function>
+
 </para>
 
 @void: 
- Returns: the default #GConfEngine.
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_engine_get_for_address ##### -->
diff --git a/doc/gconf/tmpl/gconf-listeners.sgml b/doc/gconf/tmpl/gconf-listeners.sgml
index 37d2ac8..d2d5782 100644
--- a/doc/gconf/tmpl/gconf-listeners.sgml
+++ b/doc/gconf/tmpl/gconf-listeners.sgml
@@ -24,11 +24,7 @@ convenience wrapper.
 
 <!-- ##### STRUCT GConfListeners ##### -->
 <para>
-The #GConfListeners structure contains nothing other than a dummy pointer. Internally 
-the data about listeners is maintained through a listener table structure,
-LTable which contains data like the namespace, an array to hold the listeners, count of
-active listeners,value to be given to the next connection and the list of connection indices
-to be recycled. There is also a Listener structure maintaining data pertaining to listeners. 
+
 </para>
 
 
diff --git a/doc/gconf/tmpl/gconf-schema.sgml b/doc/gconf/tmpl/gconf-schema.sgml
index a034d42..f0d2ec1 100644
--- a/doc/gconf/tmpl/gconf-schema.sgml
+++ b/doc/gconf/tmpl/gconf-schema.sgml
@@ -32,7 +32,7 @@ be</emphasis>, not what the type actually is.
 
 <!-- ##### STRUCT GConfSchema ##### -->
 <para>
-An opaque data type representing a description of a key-value pair.
+
 </para>
 
 
diff --git a/doc/gconf/tmpl/gconf-value.sgml b/doc/gconf/tmpl/gconf-value.sgml
index 93eb541..91d6798 100644
--- a/doc/gconf/tmpl/gconf-value.sgml
+++ b/doc/gconf/tmpl/gconf-value.sgml
@@ -131,15 +131,11 @@ Returns the type of the list elements in a #GConfValue with type
 
 <!-- ##### FUNCTION gconf_value_get_list ##### -->
 <para>
-Returns a #GSList containing #GConfValue objects. Each #GConfValue in
-the returned list will have the type returned by
-gconf_value_get_list_type(). Remember that the empty #GSList is equal to
-<symbol>NULL</symbol>.  The list is not a copy; it is "owned" by the
-#GConfValue and will be destroyed when the #GConfValue is destroyed.
+
 </para>
 
- value: a #GConfValue.
- Returns: a #GList.
+ value: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_value_get_car ##### -->
diff --git a/doc/gconf/tmpl/gconf.sgml b/doc/gconf/tmpl/gconf.sgml
index d936dbe..7b802dd 100644
--- a/doc/gconf/tmpl/gconf.sgml
+++ b/doc/gconf/tmpl/gconf.sgml
@@ -95,24 +95,15 @@ gconf_engine_notify_add().
 
 <!-- ##### FUNCTION gconf_engine_notify_add ##### -->
 <para>
-Registers a notification request with the <application>gconfd</application>
-server.  The server will notify the client when any key at or below
- namespace_section is set or unset. Try to watch the smallest possible part of
-the namespace; otherwise you will slow down the server and your application with
-unnecessary notifications. Note that you should prefer gconf_client_notify_add()
-if you're using the #GObject wrapper library, because
-gconf_client_notify_add() does not require a client-server conversation for
-every callback. gconf_engine_notify_add() requests a different server notification for
-every callback. The function returns an ID you can use to remove the
-notification request; 0 is an invalid ID, and is returned if an error occurs.
-</para>
-
- conf: a #GConfEngine to monitor for changes.
- namespace_section: the directory or key to watch; you will be notified of changes at or below this point.
- func: the callback to invoke when a notification is received from the server.
- user_data: the data to pass to the callback.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: an ID for the notification request, or 0 on error.
+
+</para>
+
+ conf: 
+ namespace_section: 
+ func: 
+ user_data: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_engine_notify_remove ##### -->
@@ -256,30 +247,24 @@ schema associations into the database during "make install."
 
 <!-- ##### FUNCTION gconf_engine_all_entries ##### -->
 <para>
-Lists the key-value pairs in @dir. Does not list subdirectories; for
-that use gconf_engine_all_dirs(). The returned list contains #GConfEntry
-objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key
-and a value. The list is not recursive, it contains only the immediate
-children of @dir.  To free the returned list, gconf_entry_free()
-each list element, then g_slist_free() the list itself.
+
 </para>
 
- conf: a #GConfEngine.
- dir: Directory to list.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: List of #GConfEntry.
+ conf: 
+ dir: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_engine_all_dirs ##### -->
 <para>
-Lists the subdirectories in @dir. The returned list contains allocated
-strings. Each string is the absolute path of a subdirectory. You should g_free() each string in the list, then g_slist_free() the list itself.
+
 </para>
 
- conf: a #GConfEngine.
- dir: Directory to get subdirectories from.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: List of allocated subdirectory names.
+ conf: 
+ dir: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_engine_suggest_sync ##### -->
@@ -464,85 +449,25 @@ stored at @key, an error is returned. On error, or if @key is unset,
 
 <!-- ##### FUNCTION gconf_engine_get_schema ##### -->
 <para>
-Requests the schema (%GCONF_VALUE_SCHEMA) stored at @key.
-Automatically performs type-checking, so if a non-schema is stored at
- key, an error is returned. If no value is set or an error occurs,
-<symbol>NULL</symbol> is returned.
+
 </para>
 
- conf: a #GConfEngine.
- key: key you want the value of.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained.
+ conf: 
+ key: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_engine_get_list ##### -->
 <para>
-Requests the list (%GCONF_VALUE_LIST) stored at @key.  Automatically
-performs type-checking, so if a non-list is stored at @key, or the
-list does not contain elements of type @list_type, an error is
-returned. If no value is set or an error occurs, <symbol>NULL</symbol>
-is returned. Note that <symbol>NULL</symbol> is also the empty list,
-so if you need to distinguish the empty list from an unset value, you
-must use gconf_engine_get () to obtain a raw #GConfValue.
-</para>
 
-<para>
-<emphasis>Remember that GConf lists can only store primitive types:
-%GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
-%GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember
-that lists must be uniform, you may not mix types in the same list.
 </para>
 
-<para>
-The type of the list elements depends on @list_type. A #GConfValue
-with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue
-objects. gconf_engine_get_list() automatically converts to primitive C
-types. Thus, the list-&gt;data fields in the returned list 
-contain:
- 
-<informaltable pgwide="1" frame="none">
-<tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
-<tbody>
-
-<row>
-<entry>%GCONF_VALUE_INT</entry>
-<entry>The integer itself, converted with GINT_TO_POINTER()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_BOOL</entry>
-<entry>The bool itself, converted with GINT_TO_POINTER()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_FLOAT</entry>
-<entry>A pointer to #gdouble, which should be freed with g_free()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_STRING</entry>
-<entry>A pointer to #gchar, which should be freed with g_free()</entry>
-</row>
-
-<row>
-<entry>%GCONF_VALUE_SCHEMA</entry>
-<entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry>
-</row>
-
-</tbody></tgroup></informaltable>
-
-In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must
-g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must
-gconf_schema_free() each element. In all cases you must free the
-list itself with g_slist_free().
-</para>
-
- conf: a #GConfEngine.
- key: key you want the value of.
- list_type: type of each list element.
- err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
- Returns: an allocated list, with elements as described above.
+ conf: 
+ key: 
+ list_type: 
+ err: 
+ Returns: 
 
 
 <!-- ##### FUNCTION gconf_engine_get_pair ##### -->
diff --git a/gconf/gconf-changeset.c b/gconf/gconf-changeset.c
index c797d81..4890fce 100644
--- a/gconf/gconf-changeset.c
+++ b/gconf/gconf-changeset.c
@@ -106,6 +106,15 @@ gconf_change_set_unref    (GConfChangeSet* cs)
     }
 }
 
+/**
+ * gconf_change_set_set_user_data: (skip)
+ * @cs: a #GConfChangeSet.
+ * @data: a #gpointer.
+ * @dnotify: a pointer to the function to be called during destroy.
+ *
+ * Sets the user_data and the destroy notification function fields of the
+ * #GConfChangeSet.
+ */
 void
 gconf_change_set_set_user_data (GConfChangeSet *cs,
                                 gpointer        data,
@@ -118,6 +127,14 @@ gconf_change_set_set_user_data (GConfChangeSet *cs,
   cs->dnotify = dnotify;
 }
 
+/**
+ * gconf_change_set_get_user_data: (skip)
+ * @cs: a #GConfChangeSet.
+ *
+ * Returns the user_data field of the #GConfChangeSet.
+ *
+ * Return value: a pointer to the user_data.
+ */
 gpointer
 gconf_change_set_get_user_data (GConfChangeSet *cs)
 {
@@ -207,6 +224,18 @@ foreach(gpointer key, gpointer value, gpointer user_data)
   (* fd->func) (fd->cs, c->key, c->value, fd->user_data);
 }
 
+/**
+ * gconf_change_set_foreach:
+ * @cs: a #GConfChangeSet.
+ * @func: (scope call): function to call for each change in the change set.
+ * @user_data: user data to pass to the #GConfChangeSetForeachFunc.
+ *
+ * Iterates over a #GConfChangeSet by calling a
+ * #GConfChangeSetForeachFunc for each change in the set. See the
+ * description of #GConfChangeSetForeachFunc for details.  You may not
+ * call gconf_change_set_remove() during the iteration, because you'll
+ * confuse the internal data structures and cause memory corruption.
+ */
 void
 gconf_change_set_foreach  (GConfChangeSet* cs,
                            GConfChangeSetForeachFunc func,
diff --git a/gconf/gconf-client.c b/gconf/gconf-client.c
index d22c326..f1df54a 100644
--- a/gconf/gconf-client.c
+++ b/gconf/gconf-client.c
@@ -56,6 +56,13 @@ trace (const char *format, ...)
 
 static GConfClientErrorHandlerFunc global_error_handler = NULL;
 
+/**
+ * gconf_client_set_global_default_error_handler: (skip)
+ * @func: pointer to the function to be called for error handling.
+ *
+ * Set @func as the default error handler for the #GConfClient. This handler would be called
+ * for all #GConfClient internal errors.
+ */
 void
 gconf_client_set_global_default_error_handler(GConfClientErrorHandlerFunc func)
 {
@@ -422,6 +429,18 @@ notify_from_server_callback (GConfEngine* conf, guint cnxn_id,
  */
 
 
+/**
+ * gconf_client_get_default:
+ *
+ * Creates a new #GConfClient using the default #GConfEngine. Normally this is the
+ * engine you want. If someone else is already using the default
+ * #GConfClient, this function returns the same one they're using, but
+ * with the reference count incremented. So you have to unref either way.
+ *
+ * It's important to call g_type_init() before using this GObject, to initialize the type system.
+ *
+ * Return value: (transfer full): a new #GConfClient. g_object_unref() when you're done.
+ */
 GConfClient*
 gconf_client_get_default (void)
 {
@@ -451,6 +470,18 @@ gconf_client_get_default (void)
   return client;
 }
 
+/**
+ * gconf_client_get_for_engine:
+ * @engine: the #GConfEngine to use.
+ *
+ * Creates a new #GConfClient with a specific #GConfEngine. Only specialized
+ * configuration-related programs should need to call this function. The
+ * returned #GConfClient should be unref'd when you're done with g_object_unref().
+ * Remember to avoid using the #GConfEngine directly once you have a #GConfClient
+ * wrapper.
+ *
+ * Return value: (transfer full): a new #GConfClient.
+ */
 GConfClient*
 gconf_client_get_for_engine (GConfEngine* engine)
 {
@@ -1086,6 +1117,22 @@ copy_entry_list (GSList *list)
   return copy;
 }
 
+/**
+ * gconf_client_all_entries:
+ * @client: a #GConfClient.
+ * @dir: directory to list.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ *
+ * Lists the key-value pairs in @dir. Does not list subdirectories; for
+ * that use gconf_client_all_dirs(). The returned list contains #GConfEntry
+ * objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key
+ * and a value. The list is not recursive, it contains only the immediate
+ * children of @dir.  To free the returned list, gconf_entry_free()
+ * each list element, then g_slist_free() the list itself.
+ * Just like gconf_engine_all_entries (), but uses #GConfClient caching and error-handling features.
+ *
+ * Return value: (element-type GConfEntry) (transfer full): List of #GConfEntry.
+ */
 GSList*
 gconf_client_all_entries    (GConfClient* client,
                              const gchar* dir,
@@ -1138,6 +1185,20 @@ gconf_client_all_entries    (GConfClient* client,
   return retval;
 }
 
+/**
+ * gconf_client_all_dirs:
+ * @client: a #GConfClient.
+ * @dir: directory to get subdirectories from.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ *
+ * Lists the subdirectories in @dir. The returned list contains
+ * allocated strings. Each string is the absolute path of a
+ * subdirectory. You should g_free() each string in the list, then
+ * g_slist_free() the list itself.  Just like gconf_engine_all_dirs(),
+ * but uses #GConfClient caching and error-handling features.
+ *
+ * Return value: (element-type utf8) (transfer full): List of allocated subdirectory names.
+ */
 GSList*
 gconf_client_all_dirs       (GConfClient* client,
                              const gchar* dir, GError** err)
@@ -1628,6 +1689,72 @@ gconf_client_get_schema  (GConfClient* client,
     }
 }
 
+/**
+ * gconf_client_get_list: (skip)
+ * @client: a #GConfClient.
+ * @key: key you want the value of.
+ * @list_type: type of each list element.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ *
+ * Requests the list (%GCONF_VALUE_LIST) stored at @key.  Automatically
+ * performs type-checking, so if a non-list is stored at @key, or the
+ * list does not contain elements of type @list_type, an error is
+ * returned. If no value is set or an error occurs, <symbol>NULL</symbol>
+ * is returned. Note that <symbol>NULL</symbol> is also the empty list,
+ * so if you need to distinguish the empty list from an unset value, you
+ * must use gconf_client_get () to obtain a raw #GConfValue.
+ *
+ * <emphasis>Remember that GConf lists can only store primitive types:
+ * %GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
+ * %GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember
+ * that lists must be uniform, you may not mix types in the same list.
+ *
+ * The type of the list elements depends on @list_type. A #GConfValue
+ * with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue
+ * objects. gconf_client_get_list() automatically converts to primitive C
+ * types. Thus, the list-&gt;data fields in the returned list
+ * contain:
+ *  
+ * <informaltable pgwide="1" frame="none">
+ * <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
+ * <tbody>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_INT</entry>
+ * <entry>The integer itself, converted with GINT_TO_POINTER()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_BOOL</entry>
+ * <entry>The bool itself, converted with GINT_TO_POINTER()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_FLOAT</entry>
+ * <entry>A pointer to #gdouble, which should be freed with g_free()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_STRING</entry>
+ * <entry>A pointer to #gchar, which should be freed with g_free()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_SCHEMA</entry>
+ * <entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry>
+ * </row>
+ *  
+ * </tbody></tgroup></informaltable>
+ *  
+ * In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must
+ * g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must
+ * gconf_schema_free() each element. In all cases you must free the
+ * list itself with g_slist_free().
+ *
+ * Just like gconf_engine_get_list (), but uses #GConfClient caching and error-handling features.
+ *
+* Return value: an allocated list, with elements as described above.
+*/
 GSList*
 gconf_client_get_list    (GConfClient* client, const gchar* key,
                           GConfValueType list_type, GError** err)
diff --git a/gconf/gconf-engine.h b/gconf/gconf-engine.h
index 4185d96..91a3ab5 100644
--- a/gconf/gconf-engine.h
+++ b/gconf/gconf-engine.h
@@ -25,6 +25,13 @@
 
 G_BEGIN_DECLS
 
+/* Skipped from introspection because it's not an object or registered as boxed */
+/**
+ * GConfEngine: (skip)
+ *
+ * An opaque data type representing one or more configuration sources.
+ */
+
 /* A configuration engine (stack of config sources); normally there's
  * just one of these on the system.  
  */
diff --git a/gconf/gconf-listeners.h b/gconf/gconf-listeners.h
index 69f7bad..eb06f1d 100644
--- a/gconf/gconf-listeners.h
+++ b/gconf/gconf-listeners.h
@@ -24,6 +24,17 @@
 
 G_BEGIN_DECLS
 
+/* Skipped from introspection because it's not registered as boxed */
+/**
+ * GConfListeners: (skip)
+ *
+ * The #GConfListeners structure contains nothing other than a dummy pointer. Internally 
+ * the data about listeners is maintained through a listener table structure,
+ * LTable which contains data like the namespace, an array to hold the listeners, count of
+ * active listeners,value to be given to the next connection and the list of connection indices
+ * to be recycled. There is also a Listener structure maintaining data pertaining to listeners.
+ */
+
 /*
  * The listeners object is used to store listeners who want notification
  * of changes in a namespace section.
diff --git a/gconf/gconf-schema.h b/gconf/gconf-schema.h
index fe6975c..4821a65 100644
--- a/gconf/gconf-schema.h
+++ b/gconf/gconf-schema.h
@@ -27,6 +27,13 @@
 
 G_BEGIN_DECLS
 
+/* Skipped from introspection because it's not registered as boxed */
+/**
+ * GConfSchema: (skip)
+ *
+ * An opaque data type representing a description of a key-value pair.
+ */
+
 /*
  *  A "schema" is a value that describes a key-value pair.
  *  It might include the type of the pair, documentation describing 
diff --git a/gconf/gconf-value.c b/gconf/gconf-value.c
index 499403d..da9d743 100644
--- a/gconf/gconf-value.c
+++ b/gconf/gconf-value.c
@@ -895,6 +895,18 @@ gconf_value_get_list_type (const GConfValue *value)
   return REAL_VALUE (value)->d.list_data.type;
 }
 
+/**
+ * gconf_value_get_list:
+ * @value: a #GConfValue.
+ *
+ * Returns a #GSList containing #GConfValue objects. Each #GConfValue in
+ * the returned list will have the type returned by
+ * gconf_value_get_list_type(). Remember that the empty #GSList is equal to
+ * <symbol>NULL</symbol>.  The list is not a copy; it is "owned" by the
+ * #GConfValue and will be destroyed when the #GConfValue is destroyed.
+ *
+ * Return value: (element-type GConfValue) (transfer none): a #GList.
+ */
 GSList*
 gconf_value_get_list (const GConfValue *value)
 {
diff --git a/gconf/gconf-value.h b/gconf/gconf-value.h
index 1f57510..d8d3c82 100644
--- a/gconf/gconf-value.h
+++ b/gconf/gconf-value.h
@@ -126,6 +126,11 @@ gchar*      gconf_value_encode               (GConfValue  *val);
  * info into GConfEntry, though the transition isn't complete.
  */
 
+/* Skipped from introspection because it's not registered as boxed */
+/**
+ * GConfMetaInfo: (skip)
+ *
+ */
 typedef struct _GConfMetaInfo GConfMetaInfo;
 
 struct _GConfMetaInfo {
diff --git a/gconf/gconf.c b/gconf/gconf.c
index 4261524..0b59944 100644
--- a/gconf/gconf.c
+++ b/gconf/gconf.c
@@ -558,6 +558,19 @@ gconf_engine_get_local_for_addresses (GSList  *addresses,
   return conf;
 }
 
+/**
+ * gconf_engine_get_default: (skip)
+ *
+ * Returns the default #GConfEngine. All clients should use this, unless 
+ * they are special configuration-related tools. The caller of this
+ * function assumes one reference count, and must call
+ * gconf_engine_unref() at some point. It's fairly important to unref the
+ * #GConfEngine, to cleanly close the connection to
+ * <application>gconfd</application>. So if possible close the connection
+ * before exiting your application.
+ *
+ * Return value: (transfer full): the default #GConfEngine.
+ */
 GConfEngine*
 gconf_engine_get_default (void)
 {
@@ -791,6 +804,28 @@ gconf_engine_get_user_data  (GConfEngine   *engine)
   return engine->user_data;
 }
 
+/**
+ * gconf_engine_notify_add: (skip)
+ * @conf: a #GConfEngine to monitor for changes.
+ * @namespace_section: the directory or key to watch; you will be notified of changes at or below this point.
+ * @func: the callback to invoke when a notification is received from the server.
+ * @user_data: the data to pass to the callback.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ * Return value: an ID for the notification request, or 0 on error.
+ *
+ * Registers a notification request with the <application>gconfd</application>
+ * server.  The server will notify the client when any key at or below
+ * @namespace_section is set or unset. Try to watch the smallest possible part of
+ * the namespace; otherwise you will slow down the server and your application with
+ * unnecessary notifications. Note that you should prefer gconf_client_notify_add()
+ * if you're using the #GObject wrapper library, because
+ * gconf_client_notify_add() does not require a client-server conversation for
+ * every callback. gconf_engine_notify_add() requests a different server notification for
+ * every callback. The function returns an ID you can use to remove the
+ * notification request; 0 is an invalid ID, and is returned if an error occurs.
+ *
+ * Returns value: an ID for the notification request, or 0 on error.
+ */
 guint
 gconf_engine_notify_add(GConfEngine* conf,
                         const gchar* namespace_section,
@@ -1604,6 +1639,21 @@ qualify_entries (GSList *entries, const char *dir)
     }
 }
 
+/**
+ * gconf_engine_all_entries:
+ * @conf: a #GConfEngine.
+ * @dir: Directory to list.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ *
+ * Lists the key-value pairs in @dir. Does not list subdirectories; for
+ * that use gconf_engine_all_dirs(). The returned list contains #GConfEntry
+ * objects. A #GConfEntry contains an <emphasis>absolute</emphasis> key
+ * and a value. The list is not recursive, it contains only the immediate
+ * children of @dir.  To free the returned list, gconf_entry_free()
+ * each list element, then g_slist_free() the list itself.
+ *
+ * Returns value: (element-type GConfEntry) (transfer full): List of #GConfEntry.
+ */
 GSList*      
 gconf_engine_all_entries(GConfEngine* conf, const gchar* dir, GError** err)
 {
@@ -1774,6 +1824,19 @@ qualify_keys (GSList *keys, const char *dir)
     }
 }
 
+/**
+ * gconf_engine_all_dirs:
+ * @conf: a #GConfEngine.
+ * @dir: Directory to get subdirectories from.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ *
+ * Lists the subdirectories in @dir. The returned list contains
+ * allocated strings. Each string is the absolute path of a
+ * subdirectory. You should g_free() each string in the list, then
+ * g_slist_free() the list itself.
+ *
+ * Returns value: (element-type utf8) (transfer full): List of allocated subdirectory names.
+ */
 GSList*      
 gconf_engine_all_dirs(GConfEngine* conf, const gchar* dir, GError** err)
 {
@@ -3256,6 +3319,20 @@ gconf_engine_get_bool  (GConfEngine* conf, const gchar* key,
     }
 }
 
+/**
+ * gconf_engine_get_schema: (skip)
+ * @conf: a #GConfEngine.
+ * @key: key you want the value of.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ * @Returns: the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained.
+ *
+ * Requests the schema (%GCONF_VALUE_SCHEMA) stored at @key.
+ * Automatically performs type-checking, so if a non-schema is stored at
+ * @key, an error is returned. If no value is set or an error occurs,
+ * <symbol>NULL</symbol> is returned.
+ *
+ * Return value: (transfer full): the value of @key as an allocated #GConfSchema, or <symbol>NULL</symbol> if no value was obtained.
+ */
 GConfSchema* 
 gconf_engine_get_schema  (GConfEngine* conf, const gchar* key, GError** err)
 {
@@ -3288,6 +3365,70 @@ gconf_engine_get_schema  (GConfEngine* conf, const gchar* key, GError** err)
     }
 }
 
+/**
+ * gconf_engine_get_list: (skip)
+ * @conf: a #GConfEngine.
+ * @key: key you want the value of.
+ * @list_type: type of each list element.
+ * @err: the return location for an allocated #GError, or <symbol>NULL</symbol> to ignore errors.
+ *
+ * Requests the list (%GCONF_VALUE_LIST) stored at @key.  Automatically
+ * performs type-checking, so if a non-list is stored at @key, or the
+ * list does not contain elements of type @list_type, an error is
+ * returned. If no value is set or an error occurs, <symbol>NULL</symbol>
+ * is returned. Note that <symbol>NULL</symbol> is also the empty list,
+ * so if you need to distinguish the empty list from an unset value, you
+ * must use gconf_engine_get () to obtain a raw #GConfValue.
+ *
+ * <emphasis>Remember that GConf lists can only store primitive types:
+ * %GCONF_VALUE_FLOAT, %GCONF_VALUE_INT, %GCONF_VALUE_BOOL,
+ * %GCONF_VALUE_STRING, %GCONF_VALUE_SCHEMA.</emphasis> Also remember
+ * that lists must be uniform, you may not mix types in the same list.
+ *
+ * The type of the list elements depends on @list_type. A #GConfValue
+ * with type %GCONF_VALUE_LIST normally stores a list of more #GConfValue
+ * objects. gconf_engine_get_list() automatically converts to primitive C
+ * types. Thus, the list-&gt;data fields in the returned list
+ * contain:
+ *  
+ * <informaltable pgwide="1" frame="none">
+ * <tgroup cols="2"><colspec colwidth="2*"/><colspec colwidth="8*"/>
+ * <tbody>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_INT</entry>
+ * <entry>The integer itself, converted with GINT_TO_POINTER()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_BOOL</entry>
+ * <entry>The bool itself, converted with GINT_TO_POINTER()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_FLOAT</entry>
+ * <entry>A pointer to #gdouble, which should be freed with g_free()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_STRING</entry>
+ * <entry>A pointer to #gchar, which should be freed with g_free()</entry>
+ * </row>
+ *  
+ * <row>
+ * <entry>%GCONF_VALUE_SCHEMA</entry>
+ * <entry>A pointer to #GConfSchema, which should be freed with gconf_schema_free()</entry>
+ * </row>
+ *  
+ * </tbody></tgroup></informaltable>
+ *  
+ * In the %GCONF_VALUE_FLOAT and %GCONF_VALUE_STRING cases, you must
+ * g_free() each list element. In the %GCONF_VALUE_SCHEMA case you must
+ * gconf_schema_free() each element. In all cases you must free the
+ * list itself with g_slist_free().
+ *
+ * Return value: an allocated list, with elements as described above.
+ */
 GSList*
 gconf_engine_get_list    (GConfEngine* conf, const gchar* key,
                           GConfValueType list_type, GError** err)