[glib/new-gsettings] Document the backend api as unstable

[Matthias Clasen <matthiasc src gnome org>]

commit ac118e00bedbad1f462118671ef45bcdd8c5fc0c
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Apr 14 22:16:27 2010 -0400

    Document the backend api as unstable
    
    And protect it by G_SETTINGS_ENABLE_BACKEND to make this explicit.

 gio/gdelayedsettingsbackend.h |    1 +
 gio/gmemorysettingsbackend.h  |    1 +
 gio/gsettingsbackend.c        |   25 ++++++++++++++++++-------
 gio/gsettingsbackend.h        |    4 ++++
 4 files changed, 24 insertions(+), 7 deletions(-)
---
diff --git a/gio/gdelayedsettingsbackend.h b/gio/gdelayedsettingsbackend.h
index 7a81d49..c66ad2f 100644
--- a/gio/gdelayedsettingsbackend.h
+++ b/gio/gdelayedsettingsbackend.h
@@ -13,6 +13,7 @@
 
 #include <glib-object.h>
 
+#define G_SETTINGS_ENABLE_BACKEND
 #include <gio/gsettingsbackend.h>
 
 #define G_TYPE_DELAYED_SETTINGS_BACKEND                     (g_delayed_settings_backend_get_type ())
diff --git a/gio/gmemorysettingsbackend.h b/gio/gmemorysettingsbackend.h
index a765175..ee91fd5 100644
--- a/gio/gmemorysettingsbackend.h
+++ b/gio/gmemorysettingsbackend.h
@@ -1,6 +1,7 @@
 #ifndef _gmemorysettingsbackend_h_
 #define _gmemorysettingsbackend_h_
 
+#define G_SETTINGS_ENABLE_BACKEND
 #include <gio/gsettingsbackend.h>
 
 G_BEGIN_DECLS
diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c
index 6e814df..8b963d3 100644
--- a/gio/gsettingsbackend.c
+++ b/gio/gsettingsbackend.c
@@ -23,6 +23,7 @@
 
 #include "config.h"
 
+#define G_SETTINGS_ENABLE_BACKEND
 #include "gsettingsbackendinternal.h"
 #include "gmemorysettingsbackend.h"
 #include "giomodule-priv.h"
@@ -52,7 +53,9 @@ enum {
 
 /**
  * SECTION:gsettingsbackend
+ * @title: GSettingsBackend
  * @short_description: an interface for settings backend implementations
+ * @include: gio/gsettingsbackend.h
  *
  * The #GSettingsBackend interface defines a generic interface for
  * non-strictly-typed data that is stored in a hierarchy.
@@ -69,6 +72,14 @@ enum {
  * These trees always have strings as keys and #GVariant as values.
  * g_settings_backend_create_tree() is a convenience function to create
  * suitable trees.
+ *
+ * <note><para>
+ * The #GSettingsBackend API is exported to allow third-party
+ * implementations, but does not carry the same stability guarantees
+ * as the public GIO API. For this reason, you have to define the
+ * C preprocessor symbol #G_SETTINGS_ENABLE_BACKEND before including
+ * <filename>gio/gsettingsbackend.h</filename>
+ * </para></note>
  **/
 
 struct _GSettingsBackendWatch
@@ -170,9 +181,9 @@ is_path (const gchar *path)
  * @name: the name of the key or path that changed
  * @origin_tag: the origin tag
  *
- * Emits the changed signal on @backend.  This function should only be
- * called by the implementation itself, to indicate that a change has
- * occurred.
+ * Emits the #GSettingsBackend::changed signal on @backend.
+ * This function should only be called by the implementation itself,
+ * to indicate that a change has occurred.
  *
  * @name may refer to a specific single key (ie: not ending in '/') or
  * may refer to a set of keys (ie: ending in '/').  In the case that it
@@ -210,14 +221,14 @@ g_settings_backend_changed (GSettingsBackend    *backend,
 }
 
 /**
- * g_settings_backend_changed:
+ * g_settings_backend_keys_changed:
  * @backend: a #GSettingsBackend implementation
  * @items: the %NULL-terminated list of changed keys
  * @origin_tag: the origin tag
  *
- * Emits the changed signal on @backend.  This function should only be
- * called by the implementation itself, to indicate that a change has
- * occurred.
+ * Emits the #GSettingsBackend::keys-changed signal on @backend.
+ * This function should only be called by the implementation itself,
+ * to indicate that a change has occurred.
  *
  * The list of changed keys, relative to the root of the settings store,
  * is @prefix prepended to each of the @items.  It must either be the
diff --git a/gio/gsettingsbackend.h b/gio/gsettingsbackend.h
index f4756d1..b32d918 100644
--- a/gio/gsettingsbackend.h
+++ b/gio/gsettingsbackend.h
@@ -24,6 +24,10 @@
 #ifndef __G_SETTINGS_BACKEND_H__
 #define __G_SETTINGS_BACKEND_H__
 
+#ifndef G_SETTINGS_ENABLE_BACKEND
+#error "You must define G_SETTINGS_ENABLE_BACKEND before including <gio/gsettingsbackend.h>."
+#endif
+
 #include <glib-object.h>
 
 G_BEGIN_DECLS