[glib/new-gsettings] More doc tweaks

[Matthias Clasen <matthiasc src gnome org>]

commit a62300d873dc91e52af679211b5d556645f7a460
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Apr 15 01:47:45 2010 -0400

    More doc tweaks

 docs/reference/gio/#gio-unused.txt# |  100 -----------------------------------
 gio/gsettings.c                     |   65 ++++++++++++++++++++++
 gio/gsettingsschema.c               |   40 --------------
 3 files changed, 65 insertions(+), 140 deletions(-)
---
diff --git a/gio/gsettings.c b/gio/gsettings.c
index 9a886a8..bb334ca 100644
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -30,6 +30,71 @@
  *
  * The #GSettings class provides a convenient API for storing and retrieving
  * application settings.
+ *
+ * When creating a GSettings instance, you have to specify a schema
+ * that describes the keys in your settings and their types and default
+ * values, as well as some other information.
+ *
+ * Normally, a schema has as fixed path that determines where the settings
+ * are stored in the conceptual global tree of settings. However, schemas
+ * can also be 'relocatable', i.e. not equipped with a fixed path. This is
+ * useful e.g. when the schema describes an 'account', and you want to be
+ * able to store a arbitrary number of accounts.
+ *
+ * Unlike other configuration systems (like GConf), GSettings does not
+ * restrict keys to basic types like strings and numbers. GSettings stores
+ * values as #GVariant, and allows any #GVariantType for keys.
+ *
+ * Similar to GConf, the default values in GSettings schemas can be
+ * localized, but the localized values are stored in gettext catalogs
+ * and looked up with the domain that is specified in the gettext-domain
+ * attribute of the <tag>schemalist</tag> or <tag>schema</tag> elements
+ * and the category that is specified in the l10n attribute of the
+ * <tag>key</tag> element.
+ *
+ * GSettings uses schemas in a compact binary form that is created
+ * by the gschema-compile utility. The input is a schema description in
+ * an XML format that can be described by the following DTD:
+ * |[<![CDATA[
+ * <!ELEMENT schemalist (schema*) >
+ * <!ATTLIST schemalist gettext-domain #IMPLIED >
+ *
+ * <!ELEMENT schema (key*) >
+ * <!ATTLIST schema id             CDATA #REQUIRED
+ *                  path           CDATA #IMPLIED
+ *                  gettext-domain CDATA #IMPLIED >
+ *
+ * <!ELEMENT key (default|summary?|description?|range?|choices?) >
+ * <!-- name can only contain lowercase letters, numbers and '-' -->
+ * <!-- type must be a GVariant type string -->
+ * <!ATTLIST key name CDATA #REQUIRED
+ *               type CDATA #REQUIRED >
+ *
+ * <!-- the default value is specified a a serialized GVariant,
+ *      i.e. you have to include the quotes when specifying a string -->
+ * <!ELEMENT default (#PCDATA) >
+ * <!-- the presence of the l10n attribute marks a default value for
+ *      translation, its value is the gettext category to use -->
+ * <!ATTLIST default l10n (ctype|numeric|time|collate|
+ *                         monetary|messages|all|paper|
+ *                         name|address|telephone|
+ *                         measurement|identification) #IMPLIED >
+ *
+ * <!ELEMENT summary (#PCDATA) >
+ * <!ELEMENT description (#PCDATA) >
+ *
+ * <!ELEMENT range (min,max)  >
+ * <!ELEMENT min (#PCDATA) >
+ * <!ELEMENT max (#PCDATA) >
+ *
+ * <!ELEMENT choices (choice+) >
+ * <!ELEMENT choice (alias?) >
+ * <!ATTLIST choice value CDATA #REQUIRED >
+ * <!ELEMENT choice (alias?) >
+ * <!ELEMENT alias EMPTY >
+ * <!ATTLIST alias value CDATA #REQUIRED >
+ * ]]>
+ * ]|
  */
 
 struct _GSettingsPrivate
diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c
index a9e9851..f4103cc 100644
--- a/gio/gsettingsschema.c
+++ b/gio/gsettingsschema.c
@@ -25,46 +25,6 @@
 
 #include "gvdb/gvdb-reader.h"
 
-/*
- * The #GSettingsSchema class provides schema information (i.e. types,
- * default values and descriptions) for keys in settings.
- *
- * Schema information is required to use #GSettings.
- *
- * The source format for GSettings schemas is an XML format that can
- * be described with the following DTD:
- * |[<![CDATA[
- * <!ELEMENT schemalist (schema*) >
- * <!ATTLIST schemalist gettext-domain #IMPLIED >
- *
- * <!ELEMENT schema (key*) >
- * <!ATTLIST schema id             #REQUIRED
- *                  path           #IMPLIED
- *                  gettext-domain #IMPLIED >
- *
- * <!ELEMENT key (default|summary?|description?|range?|choices?) >
- * <!ATTLIST key name #REQUIRED
- *               type #REQUIRED >
- *
- * <!ELEMENT default (#PCDATA) >
- * <!ATTLIST default l10n #IMPLIED >
- *
- * <!ELEMENT summary (#PCDATA) >
- * <!ELEMENT description (#PCDATA) >
- *
- * <!ELEMENT range (min,max)  >
- * <!ELEMENT min (#PCDATA) >
- * <!ELEMENT max (#PCDATA) >
- *
- * <!ELEMENT choices (choice+) >
- * <!ELEMENT choice (alias?) >
- * <!ATTLIST choice value #REQUIRED >
- * <!ELEMENT choice (alias?) >
- * <!ELEMENT alias EMPTY >
- * <!ATTLIST alias value #REQUIRED >
- * ]]>
- * ]|
- */
 
 G_DEFINE_TYPE (GSettingsSchema, g_settings_schema, G_TYPE_OBJECT)