diff --git a/docs/reference/gio/migrating-dbus-glib.xml b/docs/reference/gio/migrating-dbus-glib.xml
index a8863d18d..68202d53f 100644
--- a/docs/reference/gio/migrating-dbus-glib.xml
+++ b/docs/reference/gio/migrating-dbus-glib.xml
@@ -1,35 +1,68 @@
Migrating from dbus-glib to GDBus
-
- dbus-glib functions and their GDBus counterparts
-
-
- dbus-glibGDBus
-
-
- dbus_g_bus_get()g_bus_get_sync(), also see
- g_bus_get()
- dbus_g_proxy_new_for_name()g_dbus_proxy_new_sync(), also see
- g_dbus_proxy_new()
- dbus_g_proxy_add_signal()not needed, use the generic #GDBusProxy::g-signal
- dbus_g_proxy_connect_signal()use g_signal_connect() with #GDBusProxy::g-signal
- dbus_g_connection_register_g_object()g_dbus_connection_register_object()
- dbus_g_connection_unregister_g_object()g_dbus_connection_unregister_object()
- dbus_g_object_type_install_info()introspection data is installed while registering
- an object, see g_dbus_connection_register_object()
- dbus_g_proxy_begin_call()g_dbus_proxy_invoke_method()
- dbus_g_proxy_end_call()g_dbus_proxy_invoke_method_finish()
- dbus_g_proxy_call()g_dbus_proxy_invoke_method_sync()
- dbus_g_error_domain_register()g_dbus_error_register_error_domain()
- dbus_g_error_has_name()no direct equivalent, see g_dbus_error_get_remote_error()
- dbus_g_method_return()g_dbus_method_invocation_return_value()
- dbus_g_method_return_error()g_dbus_method_invocation_return_error() and variants
- dbus_g_method_get_sender()g_dbus_method_invocation_get_sender()
-
-
-
-
- More hints for migrating from dbus-glib to GDBus will appear here shortly...
-
+
+ Conceptual differences
+
+
+ The central concepts of D-Bus are modelled in a very similar way
+ in dbus-glib and GDBus. Both have a objects representing connections,
+ proxies and method invocations. But there are some important
+ differences:
+
+
+ dbus-glib uses libdbus, GDBus doesn't. Instead, it relies on GIO
+ streams as transport layer, and has its own implementation for the
+ the D-Bus connection setup and authentication.
+
+
+ dbus-glib uses the GObject type system for method arguments and
+ return values, including a homegrown container specialization
+ mechanism. GDBus relies uses the #GVariant type system which is
+ explicitly designed to match D-Bus types.
+
+
+ The typical way to export an object in dbus-glib involves generating
+ glue code from XML introspection data using dbus-binding-tool. GDBus does not (yet?) use code generation; you are expected to
+ embed the introspection data in your application code.
+
+
+
+
+
+
+ Dbus-glib API conversion
+
+
+ dbus-glib APIs and their GDBus counterparts
+
+
+ dbus-glibGDBus
+
+
+ #DBusGConnection#GDBusConnection
+ #DBusGProxy#GDBusProxy
+ #DBusGMethodInvocation#GDBusMethodInvocatoin
+ dbus_g_bus_get()g_bus_get_sync(), also see
+ g_bus_get()
+ dbus_g_proxy_new_for_name()g_dbus_proxy_new_sync(), also see
+ g_dbus_proxy_new()
+ dbus_g_proxy_add_signal()not needed, use the generic #GDBusProxy::g-signal
+ dbus_g_proxy_connect_signal()use g_signal_connect() with #GDBusProxy::g-signal
+ dbus_g_connection_register_g_object()g_dbus_connection_register_object()
+ dbus_g_connection_unregister_g_object()g_dbus_connection_unregister_object()
+ dbus_g_object_type_install_info()introspection data is installed while registering
+ an object, see g_dbus_connection_register_object()
+ dbus_g_proxy_begin_call()g_dbus_proxy_invoke_method()
+ dbus_g_proxy_end_call()g_dbus_proxy_invoke_method_finish()
+ dbus_g_proxy_call()g_dbus_proxy_invoke_method_sync()
+ dbus_g_error_domain_register()g_dbus_error_register_error_domain()
+ dbus_g_error_has_name()no direct equivalent, see g_dbus_error_get_remote_error()
+ dbus_g_method_return()g_dbus_method_invocation_return_value()
+ dbus_g_method_return_error()g_dbus_method_invocation_return_error() and variants
+ dbus_g_method_get_sender()g_dbus_method_invocation_get_sender()
+
+
+
+
diff --git a/gio/gdbusaddress.c b/gio/gdbusaddress.c
index 923c97350..8dcb0c9b9 100644
--- a/gio/gdbusaddress.c
+++ b/gio/gdbusaddress.c
@@ -46,7 +46,7 @@
*
* Routines for working with D-Bus addresses. A D-Bus address is a string
* like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
- * is explained in detail in the D-Bus specification.
+ * is explained in detail in the D-Bus specification.
*/
/* ---------------------------------------------------------------------------------------------------- */
diff --git a/gio/gdbusintrospection.c b/gio/gdbusintrospection.c
index e1ae213b8..017209dae 100644
--- a/gio/gdbusintrospection.c
+++ b/gio/gdbusintrospection.c
@@ -41,7 +41,7 @@
* used when registering objects with g_dbus_connection_register_object().
*
* The format of D-BUs introspection XML is specified in the
- * D-Bus specification.
+ * D-Bus specification.
*/
/* ---------------------------------------------------------------------------------------------------- */