[glib/new-gsettings] Document g_settings_get_child

[Matthias Clasen <matthiasc src gnome org>]

commit ac3dfbcf8c317c423e6822c4e003dca9d191b74d
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Apr 15 10:32:28 2010 -0400

    Document g_settings_get_child

 docs/reference/gio/gio-sections.txt |    1 +
 gio/gsettings.c                     |   25 ++++++++++++++++++++++++-
 2 files changed, 25 insertions(+), 1 deletions(-)
---
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index f01ead9..5041749 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2114,6 +2114,7 @@ g_settings_set_delay_apply
 g_settings_apply
 g_settings_revert
 g_settings_get_has_unapplied
+g_settings_get_child
 <SUBSECTION Standard>
 GSettingsClass
 <SUBSECTION Private>
diff --git a/gio/gsettings.c b/gio/gsettings.c
index 6970079..1e16dd6 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -59,7 +59,7 @@
  * <!ELEMENT schemalist (schema*) >
  * <!ATTLIST schemalist gettext-domain #IMPLIED >
  *
- * <!ELEMENT schema (key*) >
+ * <!ELEMENT schema (key|child)* >
  * <!ATTLIST schema id             CDATA #REQUIRED
  *                  path           CDATA #IMPLIED
  *                  gettext-domain CDATA #IMPLIED >
@@ -90,10 +90,18 @@
  * <!ELEMENT choice (alias?) >
  * <!ELEMENT alias EMPTY >
  * <!ATTLIST alias value CDATA #REQUIRED >
+ *
+ * <!ELEMENT child EMPTY >
+ * <!ATTLIST child name  CDATA #REQUIRED
+ *                 schema CDATA #REQUIRED >
  * ]]>
  * ]|
  */
 
+/* XXX talk about key and schema naming conventions,
+ * explain child settings
+ */
+
 struct _GSettingsPrivate
 {
   GSettingsBackend *backend;
@@ -851,6 +859,21 @@ g_settings_is_writable (GSettings   *settings,
   return writable;
 }
 
+/**
+ * g_settings_get_child:
+ * @settings: a #GSettings object
+ * @name: the name of the 'child' schema
+ * @returns: 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> is the base path of @settings.
+ *
+ * The schema for the child settings object must have been declared
+ * in the schema of @settings using a <tag>child</tag> element.
+ *
+ * Since: 2.26
+ */
 GSettings *
 g_settings_get_child (GSettings   *settings,
                       const gchar *name)