gsettings: Update documentation on schema naming convention

The existing docs are a bit inconsistent in that they say to follow
the dbus convention, but then give an example that doesn't.

This commit changes things to be how Ryan says they should be.

diff --git a/docs/reference/gio/migrating-gconf.xml b/docs/reference/gio/migrating-gconf.xml
index 44d455b..9e9f1a0 100644 (file)
--- a/docs/reference/gio/migrating-gconf.xml
+++ b/docs/reference/gio/migrating-gconf.xml
@@ -205,14 +205,16 @@ produces a <filename>org.gnome.font-rendering.gschema.xml</filename> file with t
       </example>
 
       <para>
-        GSettings schemas are identified at runtime by their id (as specified
-        in the XML source file). It is recommended to use a dotted name as schema
-        id, similar in style to a DBus bus name, e.g. "org.gnome.font-rendering".
+       GSettings schemas are identified at runtime by their id (as specified
+       in the XML source file). It is recommended to use a dotted name as schema
+       id, similar in style to a D-Bus bus name, e.g. "org.gnome.SessionManager".
+       In cases where the settings are general and not specific to one application,
+       the id should not use StudlyCaps, e.g. "org.gnome.font-rendering".
        The filename used for the XML schema source is immaterial, but
        schema compiler expects the files to have the extension
        <filename>.gschema.xml</filename>. It is recommended to simply
        use the schema id as the filename, followed by this extension,
-       e.g. <filename>org.gnome.font-rendering.gschema.xml</filename>.
+       e.g. <filename>org.gnome.SessionManager.gschema.xml</filename>.
       </para>
 
       <para>

diff --git a/gio/gsettings.c b/gio/gsettings.c
index ec48006..1d0dc56 100644 (file)
--- a/gio/gsettings.c
+++ b/gio/gsettings.c
@@ -83,7 +83,11 @@
  * in the <tag class="attribute">id</tag> attribute of the
  * <tag class="starttag">schema</tag> element). The
  * convention for schema ids is to use a dotted name, similar in
- * style to a DBus bus name, e.g. "org.gnome.font-rendering".
+ * style to a D-Bus bus name, e.g. "org.gnome.SessionManager". In particular,
+ * if the settings are for a specific service that owns a D-Bus bus name,
+ * the D-Bus bus name and schema id should match. For schemas which deal
+ * with settings not associated with one named application, the id should
+ * not use StudlyCaps, e.g. "org.gnome.font-rendering".
  *
  * In addition to #GVariant types, keys can have types that have enumerated
  * types. These can be described by a <tag class="starttag">choice</tag>,
@@ -97,7 +101,7 @@
  * <example id="schema-default-values"><title>Default values</title>
  * <programlisting><![CDATA[
  * <schemalist>
- *   <schema id="org.gtk.test" path="/tests/" gettext-domain="test">
+ *   <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
  *
  *     <key name="greeting" type="s">
  *       <default l10n="messages">"Hello, earthlings"</default>
@@ -130,7 +134,7 @@
  *     <value nick="flag3" value="4"/>
  *   </enum>
  *
- *   <schema id="org.gtk.test">
+ *   <schema id="org.gtk.Test">
  *
  *     <key name="key-with-range" type="i">
  *       <range min="1" max="100"/>