Document the entire library as deprecated

9 files changed, 332 insertions, 44 deletions

diff --git a/dbus/dbus-glib.c b/dbus/dbus-glib.c
index 316e7bf..9b89cda 100644
--- a/dbus/dbus-glib.c
+++ b/dbus/dbus-glib.c
@@ -44,6 +44,9 @@
  *
  * A #DBusGConnection is a boxed type abstracting a DBusConnection from
  * libdbus.
+ *
+ * Deprecated: New code should use #GDBusConnection from the GIO library,
+ *  which is not based on libdbus or dbus-glib.
  */
 
 /**
@@ -51,6 +54,9 @@
  * @connection: the #DBusGConnection to flush
  *
  * Blocks until outgoing calls and signal emissions have been sent.
+ *
+ * Deprecated: The closest equivalent in GDBus is
+ *  #g_dbus_connection_flush_sync().
  */
 void
 dbus_g_connection_flush (DBusGConnection *connection)
@@ -65,6 +71,8 @@ dbus_g_connection_flush (DBusGConnection *connection)
  * Increment refcount on a #DBusGConnection
  * 
  * Returns: the connection that was ref'd
+ *
+ * Deprecated: New code should use #GDBusConnection instead.
  */
 DBusGConnection*
 dbus_g_connection_ref (DBusGConnection *connection)
@@ -82,6 +90,8 @@ dbus_g_connection_ref (DBusGConnection *connection)
  * @connection: the connection to unref
  * 
  * Decrement refcount on a #DBusGConnection
+ *
+ * Deprecated: New code should use #GDBusConnection instead.
  */
 void
 dbus_g_connection_unref (DBusGConnection *connection)
@@ -108,6 +118,8 @@ dbus_g_connection_unref (DBusGConnection *connection)
  *
  * A #DBusGMessage is a boxed type abstracting a DBusMessage from
  * libdbus.
+ *
+ * Deprecated: New code should use #GDBusMessage instead.
  */
 
 /**
@@ -117,6 +129,8 @@ dbus_g_connection_unref (DBusGConnection *connection)
  * Increment refcount on a #DBusGMessage
  * 
  * Returns: the message that was ref'd
+ *
+ * Deprecated: New code should use #GDBusMessage instead.
  */
 DBusGMessage*
 dbus_g_message_ref (DBusGMessage *message)
@@ -133,6 +147,8 @@ dbus_g_message_ref (DBusGMessage *message)
  * @message: the message to unref
  * 
  * Decrement refcount on a #DBusGMessage
+ *
+ * Deprecated: New code should use #GDBusMessage instead.
  */
 void
 dbus_g_message_unref (DBusGMessage *message)
@@ -159,6 +175,8 @@ dbus_g_message_unref (DBusGMessage *message)
  * A #GError enumeration for the domain %DBUS_GERROR. The values' meanings
  * can be found by looking at the comments for the corresponding constants
  * in dbus-protocol.h.
+ *
+ * Deprecated: New code should use GDBus and its #GDBusError enum instead.
  */
 
 /**
@@ -166,6 +184,8 @@ dbus_g_message_unref (DBusGMessage *message)
  *
  * Expands to a function call returning the error domain quark for #DBusGError,
  * for use with #GError.
+ *
+ * Deprecated: New code should use GDBus and its #GDBusError enum instead.
  */
 GQuark
 dbus_g_error_quark (void)
@@ -190,6 +210,9 @@ dbus_g_error_quark (void)
  * %DBUS_GERROR_REMOTE_EXCEPTION).
  *
  * Returns: %TRUE if and only if the remote error has the given name
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_error_get_remote_error().
  */
 gboolean
 dbus_g_error_has_name (GError *error, const char *name)
@@ -213,6 +236,9 @@ dbus_g_error_has_name (GError *error, const char *name)
  * and the code is %DBUS_GERROR_REMOTE_EXCEPTION.
  *
  * Returns: the D-BUS name for a remote exception.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_error_get_remote_error().
  */
 const char *
 dbus_g_error_get_name (GError *error)
@@ -232,6 +258,8 @@ dbus_g_error_get_name (GError *error)
  * %DBUS_TYPE_G_CONNECTION, which you should usually use instead.
  *
  * Returns: the GLib type
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_connection_get_g_type (void)
@@ -255,6 +283,8 @@ dbus_connection_get_g_type (void)
  *
  *
  * Returns: the GLib type
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_message_get_g_type (void)
@@ -275,6 +305,8 @@ dbus_message_get_g_type (void)
  * Expands to a function call returning the boxed #GType of a #DBusGConnection.
  *
  * Returns: the GLib type
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_connection_get_g_type (void)
@@ -295,6 +327,8 @@ dbus_g_connection_get_g_type (void)
  * Expands to a function call returning the boxed #GType of a #DBusGConnection.
  *
  * Returns: the GLib type
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_message_get_g_type (void)
@@ -326,6 +360,8 @@ dbus_g_message_get_g_type (void)
  * The return value does not have its refcount incremented.
  *
  * Returns: #DBusConnection 
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 DBusConnection*
 dbus_g_connection_get_connection (DBusGConnection *gconnection)
@@ -346,6 +382,8 @@ extern dbus_int32_t _dbus_gmain_connection_slot;
  * refcount incremented.
  *
  * Returns: #DBusGConnection 
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 DBusGConnection*
 dbus_connection_get_g_connection (DBusConnection *connection)
@@ -365,6 +403,8 @@ dbus_connection_get_g_connection (DBusConnection *connection)
  * The return value does not have its refcount incremented.
  *
  * Returns: #DBusMessage 
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 DBusMessage*
 dbus_g_message_get_message (DBusGMessage *gmessage)
diff --git a/dbus/dbus-gmain.c b/dbus/dbus-gmain.c
index dec199d..d2c4cf4 100644
--- a/dbus/dbus-gmain.c
+++ b/dbus/dbus-gmain.c
@@ -527,6 +527,8 @@ connection_setup_new_from_old (GMainContext    *context,
  * time. If called once with context A and once with context B,
  * context B replaces context A as the context monitoring the
  * connection.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_connection_setup_with_g_main (DBusConnection *connection,
@@ -604,6 +606,8 @@ dbus_connection_setup_with_g_main (DBusConnection *connection,
  * time. If called once with context A and once with context B,
  * context B replaces context A as the context monitoring the
  * connection.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_server_setup_with_g_main (DBusServer   *server,
@@ -676,6 +680,9 @@ dbus_server_setup_with_g_main (DBusServer   *server,
  * dbus_connection_setup_with_g_main() on the result.)
  *
  * Returns: a DBusConnection
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_connection_new_for_address_sync().
  */
 DBusGConnection*
 dbus_g_connection_open (const gchar  *address,
@@ -719,6 +726,9 @@ dbus_g_connection_open (const gchar  *address,
  * dbus_connection_setup_with_g_main() on the result.)
  *
  * Returns: (transfer full): a #DBusGConnection
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_connection_new_for_address_sync().
  */
 DBusGConnection *
 dbus_g_connection_open_private (const gchar  *address,
@@ -759,6 +769,9 @@ dbus_g_connection_open_private (const gchar  *address,
  * dbus_connection_setup_with_g_main() on the result.)
  *
  * Returns: a DBusConnection
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_bus_get_sync().
  */
 DBusGConnection*
 dbus_g_bus_get (DBusBusType     type,
@@ -801,6 +814,9 @@ dbus_g_bus_get (DBusBusType     type,
  * of the former function for more information on private connections.
  *
  * Returns: a DBusConnection
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_bus_get_sync().
  */
 DBusGConnection*
 dbus_g_bus_get_private (DBusBusType     type,
diff --git a/dbus/dbus-gobject.c b/dbus/dbus-gobject.c
index 4136c70..496c606 100644
--- a/dbus/dbus-gobject.c
+++ b/dbus/dbus-gobject.c
@@ -1229,6 +1229,10 @@ lookup_property_name (GObject    *object,
  * would then use #g_object_class_override_property() to implement both
  * "a-bork" and "b-bork" and D-Bus requests for "Bork" on either D-Bus interface
  * will not conflict.
+ *
+ * Deprecated: New code should use GDBus instead. There is no
+ *  equivalent for this function, because GDBus does not conflate
+ *  GObject and D-Bus property names in the same way.
  */
 void
 dbus_g_object_type_register_shadow_property (GType      iface_type,
@@ -1656,6 +1660,9 @@ gerror_to_dbus_error_message (const DBusGObjectInfo *object_info,
  *
  * The context of an asynchronous method call.  See dbus_g_method_return() and
  * dbus_g_method_return_error().
+ *
+ * Deprecated: New code should use GDBus instead. The closest
+ *  equivalent is #GDBusMethodInvocation.
  */
 struct _DBusGMethodInvocation {
   DBusGConnection *connection; /**< The connection */
@@ -2547,6 +2554,10 @@ dbus_error_to_gerror_code (const char *derr)
  * |[const char *msg = error->message;
  * size_t len = strlen(msg);
  * const char *error_name = msg+len+1;]|
+ *
+ * Deprecated: New code should use GDBus instead. GDBus' error encoding
+ *  is much simpler and more reliable, and the closest equivalent
+ *  is g_dbus_error_new_for_dbus_error().
  */
 void
 dbus_set_g_error (GError    **gerror,
@@ -2609,6 +2620,9 @@ dbus_g_error_info_free (gpointer p)
  * for the entire process.
  *
  * Since: 0.88
+ *
+ * Deprecated: New code should use GDBus instead. There is no
+ *  equivalent for this function.
  */
 void
 dbus_glib_global_set_disable_legacy_property_access (void)
@@ -2630,6 +2644,9 @@ dbus_glib_global_set_disable_legacy_property_access (void)
  * Once introspection information has been installed, instances of the
  * object registered with dbus_g_connection_register_g_object() can have
  * their methods invoked remotely.
+ *
+ * Deprecated: New code should use GDBus instead. There is no direct
+ *  equivalent for this function.
  */
 void
 dbus_g_object_type_install_info (GType                  object_type,
@@ -2673,6 +2690,9 @@ dbus_g_object_type_install_info (GType                  object_type,
  * <code>dbus_g_error_domain_register (MY_ERROR, NULL, MY_TYPE_ERROR)</code>
  * instead, then the D-Bus error string would be
  * <code>com.example.MyObject.NotHappy</code>.)
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_error_register_error_domain().
  */
 void
 dbus_g_error_domain_register (GQuark                domain,
@@ -2741,6 +2761,9 @@ object_export_object_died (gpointer user_data, GObject *dead)
  * Removes @object from any object paths at which it is exported on
  * @connection. Properties, methods, and signals
  * of the object can no longer be accessed remotely.
+ *
+ * Deprecated: New code should use GDBus instead.
+ *  The closest equivalent is g_dbus_connection_unregister_object().
  */
 void
 dbus_g_connection_unregister_g_object (DBusGConnection *connection,
@@ -2791,6 +2814,11 @@ dbus_g_connection_unregister_g_object (DBusGConnection *connection,
  *
  * Note: If an object is registered multiple times, the first registration
  * takes priority for cases such as turning an object into an object path.
+ *
+ * Deprecated: New code should use GDBus instead.
+ *  The closest equivalent is g_dbus_connection_register_object(),
+ *  but #GDBusObjectManagerServer and #GDBusObjectSkeleton provide
+ *  a higher-level API.
  */
 void
 dbus_g_connection_register_g_object (DBusGConnection       *connection,
@@ -2876,6 +2904,9 @@ dbus_g_connection_register_g_object (DBusGConnection       *connection,
  * FIXME 
  *
  * Returns: the object at path @at_path
+ *
+ * Deprecated: New code should use GDBus instead. There is no direct
+ *  equivalent for this function.
  */
 GObject *
 dbus_g_connection_lookup_g_object (DBusGConnection       *connection,
@@ -3049,6 +3080,8 @@ _dbus_gobject_lookup_marshaller (GType        rettype,
  * followed by %G_TYPE_INVALID.
  *
  * This function will not be needed once GLib includes libffi.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_object_register_marshaller (GClosureMarshal  marshaller,
@@ -3082,6 +3115,8 @@ dbus_g_object_register_marshaller (GClosureMarshal  marshaller,
  *
  * Register a #GClosureMarshal to be used for signal invocations.
  * @see_also dbus_g_object_register_marshaller()
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_object_register_marshaller_array (GClosureMarshal  marshaller,
@@ -3122,6 +3157,9 @@ dbus_g_object_register_marshaller_array (GClosureMarshal  marshaller,
  *
  * Returns: the unique name of the sender. It
  * is up to the caller to free the returned string.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_method_invocation_get_sender().
  */
 gchar *
 dbus_g_method_get_sender (DBusGMethodInvocation *context)
@@ -3143,6 +3181,9 @@ dbus_g_method_get_sender (DBusGMethodInvocation *context)
  * of the correct type due to glib binding limitations
  *
  * Returns: a #DBusMessage with the reply
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_method_invocation_return_value().
  */
 DBusMessage *
 dbus_g_method_get_reply (DBusGMethodInvocation *context)
@@ -3161,6 +3202,9 @@ dbus_g_method_get_reply (DBusGMethodInvocation *context)
  *
  * Used as a sidedoor when you can't generate dbus values
  * of the correct type due to glib binding limitations
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_method_invocation_return_value().
  */
 void
 dbus_g_method_send_reply (DBusGMethodInvocation *context, DBusMessage *reply)
@@ -3186,6 +3230,9 @@ dbus_g_method_send_reply (DBusGMethodInvocation *context, DBusMessage *reply)
  *
  * Send a return message for a given method invocation, with arguments.
  * This function also frees the sending context.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_method_invocation_return_value().
  */
 void
 dbus_g_method_return (DBusGMethodInvocation *context, ...)
@@ -3254,6 +3301,9 @@ out:
  *
  * Send a error message for a given method invocation.
  * This function also frees the sending context.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_method_invocation_return_gerror().
  */
 void
 dbus_g_method_return_error (DBusGMethodInvocation *context, const GError *error)
@@ -3285,6 +3335,9 @@ out:
  * <!-- Returns: says it all -->
  *
  * Returns: (transfer none): the @DBusGConnection from which the method was called.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_method_invocation_get_connection().
  */
 DBusGConnection *
 dbus_g_method_invocation_get_g_connection (DBusGMethodInvocation *context)
diff --git a/dbus/dbus-gproxy.c b/dbus/dbus-gproxy.c
index 429a4fd..7af9b44 100644
--- a/dbus/dbus-gproxy.c
+++ b/dbus/dbus-gproxy.c
@@ -1829,6 +1829,9 @@ dbus_g_proxy_emit_remote_signal (DBusGProxy  *proxy,
  * Called when a reply to the call represented by @call_id arrives.
  * Use dbus_g_proxy_end_call() to see whether @call_id succeeded or
  * failed, and get the arguments returned (if any) on success.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is the standard #GAsyncReadyCallback mechanism.
  */
 
 typedef struct
@@ -1951,12 +1954,19 @@ manager_begin_bus_call (DBusGProxyManager    *manager,
  * DBusGProxy:
  *
  * A #GObject representing a remote object in a D-Bus service.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is #GDBusProxy.
  */
 
 /**
  * DBusGProxyCall:
  *
  * An opaque pointer representing an asynchronous call in progress.
+ *
+ * Deprecated: New code should use GDBus instead. There is no direct
+ *  equivalent in GDBus, but the standard #GCancellable mechanism is
+ *  analogous.
  */
 
 /*
@@ -2039,6 +2049,9 @@ dbus_g_proxy_new (DBusGConnection *connection,
  * still be alive.
  *
  * Returns: new proxy object
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_new_sync().
  */
 DBusGProxy*
 dbus_g_proxy_new_for_name (DBusGConnection *connection,
@@ -2078,6 +2091,10 @@ dbus_g_proxy_new_for_name (DBusGConnection *connection,
  * of that owner rather than the generic name.
  * 
  * Returns: new proxy object, or %NULL on error
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_new_sync() with the name owner's unique name
+ *  passed as @name.
  */
 DBusGProxy*
 dbus_g_proxy_new_for_name_owner (DBusGConnection          *connection,
@@ -2112,6 +2129,9 @@ dbus_g_proxy_new_for_name_owner (DBusGConnection          *connection,
  * the specified interface and path.  Either or both may be NULL.
  *
  * Returns: new proxy object
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_new_sync().
  */
 DBusGProxy*
 dbus_g_proxy_new_from_proxy (DBusGProxy        *proxy,
@@ -2150,6 +2170,9 @@ dbus_g_proxy_new_from_proxy (DBusGProxy        *proxy,
  * applications.
  *
  * Returns: new proxy object
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_new_sync().
  */
 DBusGProxy*
 dbus_g_proxy_new_for_peer (DBusGConnection          *connection,
@@ -2182,6 +2205,10 @@ dbus_g_proxy_new_for_peer (DBusGConnection          *connection,
  * the #DBusGProxy::destroy signal.
  *
  * Returns: the bus name the proxy sends messages to
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_get_name() or g_dbus_proxy_get_name_owner(),
+ *  depending how the proxy was created.
  */
 const char*
 dbus_g_proxy_get_bus_name (DBusGProxy        *proxy)
@@ -2206,6 +2233,9 @@ dbus_g_proxy_get_bus_name (DBusGProxy        *proxy)
  * the #DBusGProxy::destroy signal.
  *
  * Returns: an object interface 
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_get_interface_name().
  */
 const char*
 dbus_g_proxy_get_interface (DBusGProxy        *proxy)
@@ -2229,6 +2259,9 @@ dbus_g_proxy_get_interface (DBusGProxy        *proxy)
  *
  * It is an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
+ *
+ * Deprecated: New code should use GDBus instead. There is no
+ *  direct equivalent for this function: construct a new proxy instead.
  */
 void
 dbus_g_proxy_set_interface (DBusGProxy        *proxy,
@@ -2259,6 +2292,9 @@ dbus_g_proxy_set_interface (DBusGProxy        *proxy,
  * the #DBusGProxy::destroy signal.
  *
  * Returns: an object path
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_get_object_path().
  */
 const char*
 dbus_g_proxy_get_path (DBusGProxy        *proxy)
@@ -2574,6 +2610,9 @@ dbus_g_proxy_end_call_internal (DBusGProxy        *proxy,
  * since you should be able to do a call with large arguments.
  * 
  * Returns: call identifier.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_call().
  */
 DBusGProxyCall *
 dbus_g_proxy_begin_call (DBusGProxy          *proxy,
@@ -2638,6 +2677,9 @@ dbus_g_proxy_begin_call (DBusGProxy          *proxy,
  * since you should be able to do a call with large arguments.
  *
  * Returns: call identifier.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_call().
  */
 DBusGProxyCall *
 dbus_g_proxy_begin_call_with_timeout (DBusGProxy          *proxy,
@@ -2699,6 +2741,9 @@ dbus_g_proxy_begin_call_with_timeout (DBusGProxy          *proxy,
  * The list should be terminated with G_TYPE_INVALID.
  *
  * Returns: %TRUE on success
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_call_finish().
  */
 gboolean
 dbus_g_proxy_end_call (DBusGProxy          *proxy,
@@ -2742,6 +2787,9 @@ dbus_g_proxy_end_call (DBusGProxy          *proxy,
  * the #DBusGProxy::destroy signal.
  *
  * Returns: %TRUE if the method succeeds, %FALSE if it fails
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_call_sync().
  */
 gboolean
 dbus_g_proxy_call (DBusGProxy        *proxy,
@@ -2802,6 +2850,9 @@ dbus_g_proxy_call (DBusGProxy        *proxy,
  * the #DBusGProxy::destroy signal.
  *
  * Returns: %TRUE if the method succeeds, %FALSE if it fails
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_call_sync().
  */
 gboolean
 dbus_g_proxy_call_with_timeout (DBusGProxy        *proxy,
@@ -2859,6 +2910,9 @@ dbus_g_proxy_call_with_timeout (DBusGProxy        *proxy,
  *
  * TODO: this particular function shouldn't die on out of memory,
  * since you should be able to do a call with large arguments.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_proxy_call() with @callback = %NULL.
  */
 void
 dbus_g_proxy_call_no_reply (DBusGProxy               *proxy,
@@ -2915,6 +2969,9 @@ dbus_g_proxy_call_no_reply (DBusGProxy               *proxy,
  *
  * It is an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_cancellable_cancel().
  */
 void
 dbus_g_proxy_cancel_call (DBusGProxy        *proxy,
@@ -2966,6 +3023,9 @@ dbus_g_proxy_cancel_call (DBusGProxy        *proxy,
  *
  * It is an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_connection_send_message().
  */
 void
 dbus_g_proxy_send (DBusGProxy          *proxy,
@@ -3021,6 +3081,8 @@ array_free_all (gpointer array)
  *
  * It is also an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_proxy_add_signal  (DBusGProxy        *proxy,
@@ -3085,6 +3147,9 @@ dbus_g_proxy_add_signal  (DBusGProxy        *proxy,
  *
  * It is an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_connection_signal_subscribe().
  */
 void
 dbus_g_proxy_connect_signal (DBusGProxy             *proxy,
@@ -3139,6 +3204,9 @@ dbus_g_proxy_connect_signal (DBusGProxy             *proxy,
  *
  * It is an error to call this method on a proxy that has emitted
  * the #DBusGProxy::destroy signal.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is g_dbus_connection_signal_unsubscribe().
  */
 void
 dbus_g_proxy_disconnect_signal (DBusGProxy             *proxy,
@@ -3201,6 +3269,8 @@ dbus_g_proxy_disconnect_signal (DBusGProxy             *proxy,
  * the #DBusGProxy::destroy signal.
  *
  * Since: 0.75
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_proxy_set_default_timeout (DBusGProxy        *proxy,
diff --git a/dbus/dbus-gthread.c b/dbus/dbus-gthread.c
index 4342864..5d937b3 100644
--- a/dbus/dbus-gthread.c
+++ b/dbus/dbus-gthread.c
@@ -36,6 +36,9 @@
  * This function may only be called
  * once and must be called prior to calling any
  * other function in the D-BUS API.
+ *
+ * Deprecated: New code should use GDBus instead. GDBus is always
+ *  thread-safe, whereas dbus-glib is never thread-safe.
  */
 void
 dbus_g_thread_init (void)
diff --git a/dbus/dbus-gtype-specialized.c b/dbus/dbus-gtype-specialized.c
index 9604ed3..4ffb74e 100644
--- a/dbus/dbus-gtype-specialized.c
+++ b/dbus/dbus-gtype-specialized.c
@@ -71,6 +71,9 @@
  * This documentation needs splitting into two pages, one for defining new
  * containers and using existing containers. I expect most users to only do
  * the latter. I also need to add some examples.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is #GVariant, which is much better-designed.
  */
 
 /**
@@ -78,6 +81,9 @@
  *
  * Expands to a function call returning the #GType of a #GArray of #gboolean
  * (corresponding to the D-Bus signature "ab").
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is `G_VARIANT_TYPE ("ab")`.
  */
 
 /**
@@ -85,6 +91,9 @@
  *
  * Expands to a function call returning the #GType of a #GArray of #gint
  * (corresponding to the D-Bus signature "ai").
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is `G_VARIANT_TYPE ("ai")`.
  */
 
 /**
@@ -92,6 +101,9 @@
  *
  * Expands to a function call returning the #GType of a #GArray of #guint
  * (corresponding to the D-Bus signature "au").
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is `G_VARIANT_TYPE ("au")`.
  */
 
 /**
@@ -99,6 +111,9 @@
  *
  * Expands to a function call returning the #GType of a #GArray of #gint64
  * (corresponding to the D-Bus signature "ax").
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is `G_VARIANT_TYPE ("ax")`.
  */
 
 /**
@@ -106,6 +121,9 @@
  *
  * Expands to a function call returning the #GType of a #GArray of #guint64
  * (corresponding to the D-Bus signature "at").
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is `G_VARIANT_TYPE ("at")`.
  */
 
 /**
@@ -116,6 +134,9 @@
  *
  * Note that this is not the same thing as a #GByteArray! dbus-glib does not
  * know about the #GByteArray type.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is %G_VARIANT_TYPE_BYTESTRING.
  */
 
 /**
@@ -128,6 +149,9 @@
  * paths), but the conventional type for such arrays is
  * <literal>(dbus_g_type_get_collection ("GPtrArray",
  * DBUS_TYPE_G_OBJECT_PATH))</literal>.
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is %G_VARIANT_TYPE_OBJECT_PATH_ARRAY.
  */
 
 /**
@@ -136,6 +160,9 @@
  * Expands to a function call returning the #GType of a #GHashTable where the
  * keys are strings and the values are also strings (corresponding to the
  * D-Bus signature "a{ss}").
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is `G_VARIANT_TYPE ("a{ss}")`.
  */
 
 /**
@@ -152,6 +179,8 @@
  *
  * There are additional members, which are reserved for future expansion and
  * must be %NULL.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -161,6 +190,8 @@
  * <!-- -->
  *
  * Returns: a new instance of @type
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -171,6 +202,8 @@
  * Frees @val according to @type. This is analogous to #GBoxedFreeFunc, but
  * can use information from @type (for instance to free the contents of a
  * container before freeing the actual container).
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -183,6 +216,8 @@
  * collection).
  *
  * Returns: a deep copy of @src
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -196,6 +231,8 @@
  * @type, containing @instance.
  *
  * Returns: %TRUE on success
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -206,6 +243,8 @@
  *
  * A library-user-supplied function, called for each element in the
  * collection when dbus_g_type_collection_value_iterate() is called.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -217,6 +256,8 @@
  *
  * Implements dbus_g_type_collection_value_iterate() for a #GValue with
  * type @type, containing @instance.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -227,6 +268,8 @@
  * Implements dbus_g_type_specialized_collection_append().
  *
  * This function should use the @val and @specialization_type members of @ctx.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -236,6 +279,8 @@
  * Implements dbus_g_type_specialized_collection_end_append().
  *
  * This function should use the @val and @specialization_type members of @ctx.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -251,6 +296,8 @@
  * A table of methods used to implement specialized collection behaviour
  * on user-defined types. At least @iterator and @append_func must be
  * implemented.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -262,6 +309,8 @@
  *
  * A library-user-supplied function, called for each key/value pair in the
  * collection when dbus_g_type_map_value_iterate() is called.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -273,6 +322,8 @@
  *
  * Implements dbus_g_type_map_value_iterate() for a #GValue with
  * type @type, containing @instance.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -285,6 +336,8 @@
  *
  * This function should use the @val and @specialization_type members of @ctx,
  * and replace any existing value with key equal to @key.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -295,6 +348,8 @@
  *
  * A table of methods used to implement specialized collection behaviour
  * on user-defined types. Both methods must be implemented.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -309,6 +364,8 @@
  * containing @instance.
  *
  * Returns: %TRUE on success
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -323,6 +380,8 @@
  * containing @instance.
  *
  * Returns: %TRUE on success
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 /**
@@ -333,6 +392,8 @@
  *
  * A table of methods used to implement specialized collection behaviour
  * on user-defined types. Both methods must be implemented.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 typedef enum {
@@ -384,6 +445,8 @@ specialized_init (gpointer arg G_GNUC_UNUSED)
  * In older versions of dbus-glib, it was necessary to do this before
  * instantiating or registering any specialized type. It is now done
  * automatically whenever necessary.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_specialized_init (void)
@@ -564,6 +627,8 @@ register_container (const char                         *name,
  * @flags: As yet unused.
  *
  * Defines a new collection container.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_register_collection (const char                                   *name,
@@ -595,6 +660,8 @@ _dbus_g_type_register_collection (const char                                   *
  * @flags: As yet unused.
  *
  * Defines a new map container.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_register_map (const char                            *name,
@@ -624,6 +691,8 @@ _dbus_g_type_register_map (const char                            *name,
  * @flags: As yet unused.
  *
  * Defines a new struct container.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_register_struct (const char                             *name,
@@ -653,6 +722,8 @@ _dbus_g_type_register_struct (const char                             *name,
  * Peek the vtable for a given map specialization
  *
  * Returns: the vtable
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 const DBusGTypeSpecializedMapVtable* dbus_g_type_map_peek_vtable (GType map_type)
 {
@@ -672,6 +743,8 @@ const DBusGTypeSpecializedMapVtable* dbus_g_type_map_peek_vtable (GType map_type
  * Peek the vtable for a given collection specialization
  *
  * Returns: the vtable
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 const DBusGTypeSpecializedCollectionVtable* dbus_g_type_collection_peek_vtable (GType collection_type)
 {
@@ -691,6 +764,8 @@ const DBusGTypeSpecializedCollectionVtable* dbus_g_type_collection_peek_vtable (
  * Peek the vtable for a given struct specialization
  *
  * Returns: the vtable
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 const DBusGTypeSpecializedStructVtable* dbus_g_type_struct_peek_vtable (GType struct_type)
 {
@@ -788,6 +863,8 @@ lookup_or_register_specialized (const char  *container,
  * creating the type if not already created.
  *
  * Returns: the #GType of that instance
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_collection (const char *container,
@@ -806,6 +883,8 @@ dbus_g_type_get_collection (const char *container,
  * creating the type if not already created.
  *
  * Returns: the #GType of that instance
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_map (const char   *container,
@@ -828,6 +907,8 @@ dbus_g_type_get_map (const char   *container,
  * creating the type if not already created.
  *
  * Returns: the #GType of that instance
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_structv (const char   *container,
@@ -847,6 +928,8 @@ dbus_g_type_get_structv (const char   *container,
  * creating the type if not already created.
  *
  * Returns: the #GType of that instance
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_struct (const char *container,
@@ -883,6 +966,8 @@ dbus_g_type_get_struct (const char *container,
  * Tests if a given GType is a collection.
  *
  * Returns: true if the given GType is a collection
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 gboolean
 dbus_g_type_is_collection (GType gtype)
@@ -902,6 +987,8 @@ dbus_g_type_is_collection (GType gtype)
  * i.e. it was created with dbus_g_type_get_map().
  *
  * Returns: true if the given GType is a map
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 gboolean
 dbus_g_type_is_map (GType gtype)
@@ -921,6 +1008,8 @@ dbus_g_type_is_map (GType gtype)
  * i.e. it was created with dbus_g_type_get_struct()
  *
  * Returns: true if the given GType is a struct
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 gboolean
 dbus_g_type_is_struct (GType gtype)
@@ -953,6 +1042,8 @@ get_specialization_index (GType gtype, guint i)
  * It is an error to call this function on a non-collection type.
  *
  * Returns: the element type for a given collection GType.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_collection_specialization (GType gtype)
@@ -969,6 +1060,8 @@ dbus_g_type_get_collection_specialization (GType gtype)
  * It is an error to call this function on a non-map type.
  *
  * Returns: the key type for a given map #GType.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_map_key_specialization (GType gtype)
@@ -985,6 +1078,8 @@ dbus_g_type_get_map_key_specialization (GType gtype)
  * It is an error to call this function on a non-map type.
  *
  * Returns: the value type for a given map GType.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_map_value_specialization (GType gtype)
@@ -1003,6 +1098,8 @@ dbus_g_type_get_map_value_specialization (GType gtype)
  *
  * Returns: the type for a given member of a struct #GType,
  *    or %G_TYPE_INVALID if @member &gt;= dbus_g_type_get_struct_size()
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GType
 dbus_g_type_get_struct_member_type (GType gtype, guint member)
@@ -1019,6 +1116,8 @@ dbus_g_type_get_struct_member_type (GType gtype, guint member)
  * It is an error to call this function on a non-struct type.
  *
  * Returns: the number of members in a given struct #GType.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 guint
 dbus_g_type_get_struct_size (GType gtype)
@@ -1042,6 +1141,8 @@ dbus_g_type_get_struct_size (GType gtype)
  * then this will return a GArray with element_size of sizeof(int)
  *
  * Returns: a pointer to a newly constructed instance of the given type.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 gpointer
 dbus_g_type_specialized_construct (GType gtype)
@@ -1081,6 +1182,8 @@ dbus_g_type_specialized_construct (GType gtype)
  * can be used with this function; user-defined types might also work.
  *
  * Returns: %TRUE on success
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 gboolean
 dbus_g_type_collection_get_fixed (GValue   *value,
@@ -1119,6 +1222,8 @@ dbus_g_type_collection_get_fixed (GValue   *value,
  * The function is passed a #GValue containing the element and the given 
  * @user_data parameter. The collection may not be modified while iterating over 
  * it.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_collection_value_iterate (const GValue                           *value,
@@ -1150,6 +1255,8 @@ dbus_g_type_collection_value_iterate (const GValue                           *va
  * @specialization_type: the #GType of the array's elements
  *
  * A context for appending. There are more fields, which are private.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 typedef struct {
@@ -1170,6 +1277,8 @@ G_STATIC_ASSERT (sizeof (DBusGTypeSpecializedAppendContextReal) ==
  *
  * Create a new context for adding elements to a collection or key/value pairs 
  * to a map. You generally don't need or want to use this..
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_specialized_init_append (GValue *value, DBusGTypeSpecializedAppendContext *ctx)
@@ -1198,6 +1307,8 @@ dbus_g_type_specialized_init_append (GValue *value, DBusGTypeSpecializedAppendCo
  * @elt: a #GValue containing an element to append to the collection
  *
  * Appends a given element to the end of a collection.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_specialized_collection_append (DBusGTypeSpecializedAppendContext *ctx,
@@ -1216,6 +1327,8 @@ dbus_g_type_specialized_collection_append (DBusGTypeSpecializedAppendContext *ct
  *    for a #GValue containing a collection
  *
  * Finish appending elements to a given collection
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_specialized_collection_end_append (DBusGTypeSpecializedAppendContext *ctx)
@@ -1236,6 +1349,8 @@ dbus_g_type_specialized_collection_end_append (DBusGTypeSpecializedAppendContext
  * @val: a GValue containing a value, whose contents will be stolen by @ctx
  *
  * Inserts the given key/value pair into the map instance.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_specialized_map_append (DBusGTypeSpecializedAppendContext *ctx,
@@ -1260,6 +1375,8 @@ dbus_g_type_specialized_map_append (DBusGTypeSpecializedAppendContext *ctx,
  * The function is passed two GValues containing the key/value pair and the given 
  * @user_data parameter. The map may not be modified while iterating over 
  * it.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_type_map_value_iterate (const GValue                           *value,
@@ -1296,6 +1413,8 @@ dbus_g_type_map_value_iterate (const GValue                           *value,
  * @dbus_g_type_get_struct_member_type
  *
  * Returns: %TRUE if successful
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 gboolean
 dbus_g_type_struct_get_member (const GValue *value,
@@ -1331,6 +1450,8 @@ dbus_g_type_struct_get_member (const GValue *value,
  * the existing type of @member member of the struct.
  *
  * Returns: %TRUE if successful
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 gboolean
 dbus_g_type_struct_set_member (GValue       *value,
@@ -1368,6 +1489,8 @@ dbus_g_type_struct_set_member (GValue       *value,
  * provided.
  *
  * Returns: %FALSE on failure
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 gboolean
@@ -1424,6 +1547,8 @@ error:
  * Sets the selected members of the struct in @value.
  *
  * Returns: %FALSE on failure
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 
 gboolean
@@ -1588,6 +1713,8 @@ dbus_g_value_type_build_g_variant_type (GType type)
  * (including as a child type).
  *
  * Returns: a new #GVariant containing @value with a floating reference
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 GVariant *
 dbus_g_value_build_g_variant (const GValue *value)
diff --git a/dbus/dbus-gvalue-parse-variant.c b/dbus/dbus-gvalue-parse-variant.c
index 52c5f5b..29c4336 100644
--- a/dbus/dbus-gvalue-parse-variant.c
+++ b/dbus/dbus-gvalue-parse-variant.c
@@ -536,6 +536,8 @@ dbus_g_value_parse_variant_by_type (GVariant *variant,
  *
  * It is an error if @variant contains any #GVariant extensions not supported
  * by dbus-glib, including handles (file descriptor passing) and 'maybe' types.
+ *
+ * Deprecated: New code should use GDBus instead.
  */
 void
 dbus_g_value_parse_g_variant (GVariant *variant,
diff --git a/dbus/dbus-gvalue.c b/dbus/dbus-gvalue.c
index 6641618..fc3d78c 100644
--- a/dbus/dbus-gvalue.c
+++ b/dbus/dbus-gvalue.c
@@ -365,6 +365,9 @@ _dbus_g_value_types_init (void)
  * %DBUS_TYPE_G_OBJECT_PATH, but did not actually exist as a typedef.
  *
  * Since: 0.FIXME
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is a #GVariant (%G_TYPE_VARIANT) of type %G_VARIANT_TYPE_OBJECT_PATH.
  */
 
 /**
@@ -377,6 +380,9 @@ _dbus_g_value_types_init (void)
  * stored in a #GValue.
  *
  * Returns: a type derived from %G_TYPE_BOXED
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is a #GVariant (%G_TYPE_VARIANT) of type %G_VARIANT_TYPE_OBJECT_PATH.
  */
 GType
 dbus_g_object_path_get_g_type (void)
@@ -400,6 +406,9 @@ dbus_g_object_path_get_g_type (void)
  * %DBUS_TYPE_G_SIGNATURE, but did not actually exist as a typedef.
  *
  * Since: 0.FIXME
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is a #GVariant (%G_TYPE_VARIANT) of type %G_VARIANT_TYPE_SIGNATURE.
  */
 
 /**
@@ -412,6 +421,9 @@ dbus_g_object_path_get_g_type (void)
  * stored in a #GValue.
  *
  * Returns: a type derived from %G_TYPE_BOXED
+ *
+ * Deprecated: New code should use GDBus instead. The closest equivalent
+ *  is a #GVariant (%G_TYPE_VARIANT) of type %G_VARIANT_TYPE_SIGNATURE.
  */
 GType
 dbus_g_signature_get_g_type (void)
diff --git a/doc/reference/dbus-glib-docs.sgml b/doc/reference/dbus-glib-docs.sgml
index 7d74fe3..de21d16 100644
--- a/doc/reference/dbus-glib-docs.sgml
+++ b/doc/reference/dbus-glib-docs.sgml
@@ -14,58 +14,23 @@
     <title>Introduction</title> 
 
     <para>D-Bus is a message bus system, a simple way for applications
-    to talk to one another.</para>
-
-    <para>D-Bus supplies both a system daemon (for events such as "new
-    hardware  device   added"  or  "printer  queue   changed")  and  a
-    per-user-login-session  daemon (for general  IPC needs  among user
-    applications). Also, the message bus  is built on top of a general
-    one-to-one message passing framework, which can be used by any two
-    apps to  communicate directly  (without going through  the message
-    bus daemon).  Currently the communicating applications  are on one
-    computer,  but  TCP/IP  option  is available  and  remote  support
-    planned.</para>
-
-    <para>The D-Bus  API isn't finished yet,  and the design  is by no
-    means set in stone. One of  our main goals is for lots of projects
-    to use it, so if you wouldn't use it, by all means mail us and say
-    why -  design, licensing, indentation style, we  would rather know
-    than not know.</para>
-
-    <para>D-Bus' only <emphasis>required</emphasis> dependency is an
-    XML parser (either
-    libxml  or expat). D-Bus  includes many  language bindings  to the
-    D-Bus system,  if you  want to build  those. The list  of projects
-    using D-Bus  is growing and they  provide a wealth  of examples of
-    using the various APIs to learn from.</para>
-
-    <para>Trying out  D-Bus in sample applications is  encouraged - we
-      want to  get it  widely used and  tested.  It should  be working
-      pretty well these  days, and when it isn't  bug reports are very
-      welcome.</para>
-
-    <para>For more information on D-Bus, see
+    to talk to one another. For more information on D-Bus, see
       <ulink url="http://www.freedesktop.org/wiki/Software/dbus">
        http://www.freedesktop.org/wiki/Software/dbus</ulink>.
     </para>
 
+    <para>dbus-glib is a deprecated API for use of D-Bus from GLib
+      applications. Do not use it in new code.</para>
+
+    <para>Since version 2.26, GLib's accompanying GIO library
+      provides a high-level API for D-Bus, "GDBus", based on an
+      independent reimplementation of the D-Bus protocol. The maintainers
+      of D-Bus recommend that GLib applications should use GDBus
+      instead of dbus-glib.</para>
   </chapter>
 
   <chapter>
     <title>API Reference</title>
-    <sect1 id="api-overview">
-    <title>API for using D-BUS with GLib</title>
-
-    <para>libdbus proper is a  low-level API, these GLib bindings wrap
-    libdbus  with  a much  higher-level  approach.   The higher  level
-    approach  is  possible  because  GLib  defines  a  main  loop,  an
-    object/type system, and an out-of-memory handling policy (it exits
-    the program).  See <ulink
-    url="http://www.gtk.org">http://www.gtk.org</ulink> for GLib
-    information.</para>
-    <para>To manipulate remote objects, use DBusGProxy. </para>
-    </sect1>
-
     <xi:include href="xml/dbus-gconnection.xml"/>
     <xi:include href="xml/dbus-gobject.xml"/>
     <xi:include href="xml/dbus-gmessage.xml"/>