[glib/gdbus: 4/6] clarify docs for GBusNameOwner and GBusNameWatcher

[David Zeuthen <davidz src gnome org>]

commit 74dbceb1bfd2e24ae0df9b5a8c3d97f9072c12cd
Author: David Zeuthen <davidz redhat com>
Date:   Tue Apr 21 20:48:18 2009 -0400

    clarify docs for GBusNameOwner and GBusNameWatcher
    
    Specifically, clarify that these are low-level utility classes intended
    for language bindings and object mappings and that apps would use a
    higher level convenience layer, cf.
    
     http://bugzilla.gnome.org/show_bug.cgi?id=579571#c19
---
 docs/reference/gdbus/gdbus-docs.xml |    4 +-
 gdbus/Makefile.am                   |    6 --
 gdbus/example-gbusnameowner.c       |   90 -----------------------------------
 gdbus/gbusnameowner.c               |   21 ++++++--
 gdbus/gbusnamewatcher.c             |   18 +++++--
 gdbus/gdbusconnection.c             |    8 ++--
 6 files changed, 35 insertions(+), 112 deletions(-)

diff --git a/docs/reference/gdbus/gdbus-docs.xml b/docs/reference/gdbus/gdbus-docs.xml
index 710ca4c..36638e8 100644
--- a/docs/reference/gdbus/gdbus-docs.xml
+++ b/docs/reference/gdbus/gdbus-docs.xml
@@ -21,11 +21,11 @@
         <xi:include href="xml/gdbusmainloop.xml"/>
         <xi:include href="xml/gdbuserror.xml"/>
         <xi:include href="xml/gdbusconnection.xml"/>
+        <xi:include href="xml/gbusnameowner.xml"/>
+        <xi:include href="xml/gbusnamewatcher.xml"/>
     </chapter>
     <chapter id="convenience">
         <title>GDBus Convenience</title>
-        <xi:include href="xml/gbusnameowner.xml"/>
-        <xi:include href="xml/gbusnamewatcher.xml"/>
     </chapter>
     <chapter id="cmapping">
         <title>C Object Mapping</title>
diff --git a/gdbus/Makefile.am b/gdbus/Makefile.am
index 1d702ec..33f614b 100644
--- a/gdbus/Makefile.am
+++ b/gdbus/Makefile.am
@@ -187,11 +187,5 @@ gdbusenumtypes.c: $(gdbus_headers) gdbusenumtypes.c.template Makefile.am
 gdbus-2.0.lib: libgdbus-2.0.la gdbus.def
 	lib -machine:@LIB_EXE_MACHINE_FLAG@ -name:libgdbus-2.0-$(LT_CURRENT_MINUS_AGE).dll -def:gdbus.def -out:$@
 
-noinst_PROGRAMS = example-gbusnameowner
-
-example_gbusnameowner_SOURCES = example-gbusnameowner.c
-example_gbusnameowner_CFLAGS = $(DBUS_CFLAGS)
-example_gbusnameowner_LDADD = libgdbus-2.0.la
-
 clean-local :
 	rm -f *~
diff --git a/gdbus/example-gbusnameowner.c b/gdbus/example-gbusnameowner.c
deleted file mode 100644
index 05d4ee3..0000000
--- a/gdbus/example-gbusnameowner.c
+++ /dev/null
@@ -1,90 +0,0 @@
-
-#include <gdbus/gdbus.h>
-
-static void
-on_name_acquired (GBusNameOwner *owner,
-                  gpointer       user_data)
-{
-  g_debug ("Name acquired");
-}
-
-static void
-on_name_lost (GBusNameOwner *owner,
-              gpointer       user_data)
-{
-  g_debug ("Name lost");
-}
-
-static void
-name_owner_cb (GBusNameOwner *owner,
-               GAsyncResult  *res,
-               gpointer       user_data)
-{
-  GError *error;
-
-  error = NULL;
-  if (!g_bus_name_owner_new_finish (owner,
-                                    res,
-                                    NULL)) {
-    g_debug ("Failed to acquire name. Waiting in line.");
-  }
-}
-
-int
-main (int argc, char *argv[])
-{
-  GBusNameOwner *owner;
-  GBusNameOwnerFlags flags;
-  GMainLoop *loop;
-  GError *error;
-  GOptionContext *option_context;
-  gboolean opt_allow_replacement;
-  gboolean opt_replace;
-  GOptionEntry option_entries[] = {
-    { "allow-replacement", 'a', 0, G_OPTION_ARG_NONE, &opt_allow_replacement, "Allow replacement", NULL},
-    { "replace", 'r', 0, G_OPTION_ARG_NONE, &opt_replace, "Replace", NULL},
-    { NULL }
-  };
-
-  g_type_init ();
-
-  error = NULL;
-  option_context = g_option_context_new ("GBusNameOwner example");
-  g_option_context_add_main_entries (option_context,
-                                     option_entries,
-                                     NULL);
-  if (!g_option_context_parse (option_context,
-                               &argc,
-                               &argv,
-                               &error))
-    {
-      g_option_context_free (option_context);
-      g_printerr ("Failed to parse options: %s", error->message);
-      g_error_free (error);
-      return 1;
-    }
-  g_option_context_free (option_context);
-
-  loop = g_main_loop_new (NULL, FALSE);
-
-  flags = 0;
-  if (opt_allow_replacement)
-    flags |= G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT;
-  if (opt_replace)
-    flags |= G_BUS_NAME_OWNER_FLAGS_REPLACE;
-
-  owner = g_bus_name_owner_new (G_MESSAGE_BUS_TYPE_SESSION,
-                                "org.gtk.GDBus.ExampleName",
-                                flags,
-                                NULL,
-                                (GAsyncReadyCallback) name_owner_cb,
-                                NULL);
-  g_signal_connect (owner, "name-acquired", G_CALLBACK (on_name_acquired), NULL);
-  g_signal_connect (owner, "name-lost", G_CALLBACK (on_name_lost), NULL);
-  g_main_loop_run (loop);
-
-  g_object_unref (owner);
-  g_main_loop_unref (loop);
-
-  return 0;
-}
diff --git a/gdbus/gbusnameowner.c b/gdbus/gbusnameowner.c
index 4bf003b..0f4b3b7 100644
--- a/gdbus/gbusnameowner.c
+++ b/gdbus/gbusnameowner.c
@@ -1167,17 +1167,28 @@ g_bus_name_owner_new_internal (GMessageBusType        bus_type,
  * @callback: The callback function to invoke when finished acquiring the name.
  * @user_data: User data to pass to @callback.
  *
+ * <note><para>This class is intended for language bindings and object
+ *             mappings. If you are implementing an application, it's
+ *             easier to use the high-level g_bus_name_own() function.
+ * </para></note>
+ *
  * Creates a new #GBusNameOwner and then attempts to own @name on the
  * bus specified by @bus_type. When the attempt to own the name is
  * finished, @callback will be invoked (on the main thread) and you
  * can use g_bus_name_owner_new_finish() to get the result.
  *
- * Note that the returned object may be shared with other callers if
- * @bus_type and @name matches.
+ * Once you have the result, you can connect to the #GBusNameOwner::name-acquired
+ * and #GBusNameOwner::name-lost signals to track changes.
  *
- * This class is the preferred way to implement D-Bus
- * services. The canonical example follows.
- * <example><title>Using g_bus_name_owner_new()</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gdbus/example-gbusnameowner.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * If the connection is closed and then opened again, the #GBusNameOwner
+ * class will attempt to acquire the name.
+ *
+ * Note that the returned object may be shared with other callers if
+ * @bus_type and @name matches a previously constructed object. Also
+ * note that @flags is not used in this comparison so it's entirely
+ * possible to get a owner object that has different flags from what
+ * was passed to this function (the first one to construct the owner
+ * wins).
  *
  * Returns: A #GBusNameOwner object. Free with g_object_unref().
  **/
diff --git a/gdbus/gbusnamewatcher.c b/gdbus/gbusnamewatcher.c
index d540040..9d63606 100644
--- a/gdbus/gbusnamewatcher.c
+++ b/gdbus/gbusnamewatcher.c
@@ -1096,17 +1096,25 @@ g_bus_name_watcher_new_internal (GMessageBusType        bus_type,
  * @callback: The callback function to invoke when finished acquiring the name.
  * @user_data: User data to pass to @callback.
  *
+ * <note><para>This class is intended for language bindings and object
+ *             mappings. If you are implementing an application, it's
+ *             easier to use the high-level g_bus_name_watch() function.
+ * </para></note>
+ *
  * Creates a new #GBusNameWatcher and then check if someone owns @name
  * on the bus specified by @bus_type. When the check is finished,
  * @callback will be invoked (on the main thread) and you can use
  * g_bus_name_watcher_new_finish() to get the result.
  *
- * Note that the returned object may be shared with other callers if
- * @bus_type and @name matches.
+ * Once you have the result you can connect to the #GBusNameWatcher::name-appeared
+ * and #GBusNameWatcher::name-vanished signals to track changes.
  *
- * This class is the preferred way to implement D-Bus clients.
- * The canonical example follows.
- * <example><title>Using g_bus_name_watcher_new()</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gdbus/example-gbusnamewatcher.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
+ * If the connection is closed and then opened again, the
+ * #GBusNameWatcher class will attempt to check the if it has an
+ * owner.
+ *
+ * Note that the returned object may be shared with other callers if
+ * @bus_type and @name matches a previously constructed object.
  *
  * Returns: A #GBusNameWatcher object. Free with g_object_unref().
  **/
diff --git a/gdbus/gdbusconnection.c b/gdbus/gdbusconnection.c
index 533953a..939ac24 100644
--- a/gdbus/gdbusconnection.c
+++ b/gdbus/gdbusconnection.c
@@ -835,11 +835,11 @@ g_dbus_connection_bus_get_internal (GMessageBusType                bus_type,
  * @callback: The callback function to invoke when finished attempting opening a connection.
  * @user_data: User data to pass to @callback.
  *
- * <note><para>This class is rarely used directly; f you are
- *             implementing a D-Bus service, it's often easier to use
- *             g_bus_name_owner_new() and if you are implementing a
- *             D-Bus client it's often easier to use TODO().
+ * <note><para>This class is rarely used directly; if you are
+ *             writing an API, it's often easier to use the
+ *             g_bus_name_own() and g_bus_name_watch() APIs.
  * </para></note>
+ *
  * Creates a new #GDBusConnection object and then attempts to open a
  * connection to the message bus specified by @bus_type. When the
  * attempt to connect to the message bus is finished, @callback will