[glib/glib-2-60: 2/7] GDBusServer: Document that a GDBusAuthObserver is usually desirable

[Philip Withnall <pwithnall src gnome org>]

commit 1031e466cfb40e9144008350b2d7ee8932c1490b
Author: Simon McVittie <smcv collabora com>
Date:   Wed Jun 5 13:44:10 2019 +0100

    GDBusServer: Document that a GDBusAuthObserver is usually desirable
    
    Signed-off-by: Simon McVittie <smcv collabora com>

 gio/gdbusauthobserver.c | 8 +++++---
 gio/gdbusserver.c       | 9 +++++++++
 2 files changed, 14 insertions(+), 3 deletions(-)
---
diff --git a/gio/gdbusauthobserver.c b/gio/gdbusauthobserver.c
index 34758aa20..e89ff0e2e 100644
--- a/gio/gdbusauthobserver.c
+++ b/gio/gdbusauthobserver.c
@@ -41,9 +41,11 @@
  *
  * ## Controlling Authentication # {#auth-observer}
  *
- * For example, if you only want to allow D-Bus connections from
- * processes owned by the same uid as the server, you would use a
- * signal handler like the following:
+ * By default, a #GDBusServer or server-side #GDBusConnection will accept
+ * connections from any successfully authenticated user (but not from
+ * anonymous connections using the `ANONYMOUS` mechanism). If you only
+ * want to allow D-Bus connections from processes owned by the same uid
+ * as the server, you would use a signal handler like the following:
  * 
  * |[<!-- language="C" -->
  * static gboolean
diff --git a/gio/gdbusserver.c b/gio/gdbusserver.c
index 07757f40f..eb641a9bc 100644
--- a/gio/gdbusserver.c
+++ b/gio/gdbusserver.c
@@ -72,6 +72,11 @@
  *
  * An example of peer-to-peer communication with G-DBus can be found
  * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c).
+ *
+ * Note that a minimal #GDBusServer will accept connections from any
+ * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver
+ * that only accepts connections that have successfully authenticated
+ * as the same user that is running the #GDBusServer.
  */
 
 /**
@@ -457,6 +462,10 @@ on_run (GSocketService    *service,
  * Once constructed, you can use g_dbus_server_get_client_address() to
  * get a D-Bus address string that clients can use to connect.
  *
+ * To have control over the available authentication mechanisms and
+ * the users that are authorized to connect, it is strongly recommended
+ * to provide a non-%NULL #GDBusAuthObserver.
+ *
  * Connect to the #GDBusServer::new-connection signal to handle
  * incoming connections.
  *