[glib/new-gsettings] Add some GSettingsSchema documentation

[Matthias Clasen <matthiasc src gnome org>]

commit 102c0dacabda452de0958a47c858a9ce777f500a
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Apr 13 23:51:29 2010 -0400

    Add some GSettingsSchema documentation

 docs/reference/gio/gio-docs.xml     |    1 +
 docs/reference/gio/gio-sections.txt |   13 ++++++++
 docs/reference/gio/gio.types        |    1 +
 gio/gsettingsschema.c               |   59 ++++++++++++++++++++++++++++++++---
 4 files changed, 69 insertions(+), 5 deletions(-)
---
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 09ea58c..009214d 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -131,6 +131,7 @@
     <chapter id="settings">
         <title>Settings</title>
         <xi:include href="xml/gsettings.xml"/>
+        <xi:include href="xml/gsettingsschema.xml"/>
         <xi:include href="xml/gsettingsbackend.xml"/>
     </chapter>
     <chapter id="extending">
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 6f047df..b0a98f1 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2119,3 +2119,16 @@ GSettingsClass
 <SUBSECTION Private>
 g_settings_get_type
 </SECTION>
+
+<SECTION>
+<FILE>gsettingsschema</FILE>
+<TITLE>GSettingsSchema</TITLE>
+GSettingsSchema
+g_settings_schema_new
+g_settings_schema_get_path
+g_settings_schema_get_value
+<SUBSECTION Standard>
+GSettingsSchemaClass
+<SUBSECTION Private>
+g_settings_schema_get_type
+</SECTION>
diff --git a/docs/reference/gio/gio.types b/docs/reference/gio/gio.types
index e8e91ee..f7f691a 100644
--- a/docs/reference/gio/gio.types
+++ b/docs/reference/gio/gio.types
@@ -74,6 +74,7 @@ g_resolver_get_type
 g_seekable_get_type
 g_settings_get_type
 g_settings_backend_get_type
+g_settings_schema_get_type
 g_simple_async_result_get_type
 g_socket_address_enumerator_get_type
 g_socket_address_get_type
diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c
index 5bcc1a5..7e3479c 100644
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -18,11 +18,21 @@
  */
 
 #include "config.h"
+#include <glib.h>
+#include <glibintl.h>
 
 #include "gsettingsschema.h"
 
 #include "gvdb/gvdb-reader.h"
 
+/**
+ * SECTION:gsettingsschema
+ * @short_description: schema information for settings
+ *
+ * The #GSettingsSchema class provides schema information (i.e. types,
+ * default values and descriptions) for keys in settings.
+ */
+
 G_DEFINE_TYPE (GSettingsSchema, g_settings_schema, G_TYPE_OBJECT)
 
 struct _GSettingsSchemaPrivate
@@ -44,14 +54,14 @@ initialise_schema_sources (void)
 
       for (dir = g_get_system_data_dirs (); *dir; dir++)
         {
-	  GvdbTable *table;
+          GvdbTable *table;
           gchar *filename;
 
           filename = g_strdup_printf ("%s/glib-2.0/schemas/compiled", *dir);
-	  table = gvdb_table_new (filename, TRUE, NULL);
+          table = gvdb_table_new (filename, TRUE, NULL);
 
-	  if (table != NULL)
-	    schema_sources = g_slist_prepend (schema_sources, table);
+          if (table != NULL)
+            schema_sources = g_slist_prepend (schema_sources, table);
 
           g_free (filename);
         }
@@ -91,6 +101,17 @@ g_settings_schema_class_init (GSettingsSchemaClass *class)
   g_type_class_add_private (class, sizeof (GSettingsSchemaPrivate));
 }
 
+/**
+ * g_settings_schema_new:
+ * @name: the name of the schema
+ * @returns: a newly created #GSettingsSchema object
+ *
+ * Creates a new #GSettingsSchema object for the schema
+ * with the specified name. A settings schema with this name
+ * must have been installed, see gschema-compile.
+ *
+ * Since: 2.26
+ */
 GSettingsSchema *
 g_settings_schema_new (const gchar *name)
 {
@@ -114,10 +135,27 @@ g_settings_schema_new (const gchar *name)
   schema = g_object_new (G_TYPE_SETTINGS_SCHEMA, NULL);
   schema->priv->name = g_strdup (name);
   schema->priv->table = table;
-  
+
   return schema;
 }
 
+/**
+ * g_settings_schema_get_value:
+ * @schema: a #GSettingsSchema oject
+ * @key: the key to get the value for
+ * @options: return location for options, or %NULL
+ * @returns: a #GVariant holding the default value for @key, or %NULL
+ *
+ * Gets the default value that is defined for @key
+ * in @schema. If @options is not %NULL, then it will be set either
+ * to %NULL in the case of no options or a #GVariant containing a
+ * dictionary mapping strings to variants.
+ *
+ * You should call g_variant_unref() on the returned value when
+ * it is no longer needed.
+ *
+ * Since: 2.26
+ */
 GVariant *
 g_settings_schema_get_value (GSettingsSchema  *schema,
                              const gchar      *key,
@@ -126,6 +164,17 @@ g_settings_schema_get_value (GSettingsSchema  *schema,
   return gvdb_table_get_value (schema->priv->table, key, options);
 }
 
+/**
+ * g_settings_schema_get_path:
+ * @schema: a #GSettingsSchema object
+ * @returns: the path of the schema, or %NULL
+ *
+ * Returns the prefix which is prepended to keys described in the schema
+ * when storing them in a #GSettingsBackend. Some schemas can be stored
+ * at different prefixes, in which case this function will return %NULL.
+ *
+ * Since: 2.26
+ */
 const gchar *
 g_settings_schema_get_path (GSettingsSchema *schema)
 {