From c794261a400278db993842411e764ba435abcc34 Mon Sep 17 00:00:00 2001
From: Philip Withnall <pwithnall@endlessos.org>
Date: Thu, 10 Jun 2021 12:36:25 +0100
Subject: [PATCH] docs: Expand documentation about D-Bus GUIDs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Clarify that the terms ‘GUID’ and ‘UUID’ are used interchangeably in the
context of D-Bus, and that neither of them are an RFC 4122 UUID.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
---
 gio/gdbusconnection.c |  9 +++++++++
 gio/gdbusserver.c     |  4 +++-
 gio/gdbusutils.c      | 14 ++++++++++----
 3 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c
index d86672a31..8dcc99a7e 100644
--- a/gio/gdbusconnection.c
+++ b/gio/gdbusconnection.c
@@ -902,6 +902,15 @@ g_dbus_connection_class_init (GDBusConnectionClass *klass)
    * of the other peer here after the connection has been successfully
    * initialized.
    *
+   * Note that the
+   * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
+   * uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the
+   * term ‘GUID’ for historical reasons.
+   *
+   * Despite its name, the format of #GDBusConnection:guid does not follow
+   * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft
+   * GUID format.
+   *
    * Since: 2.26
    */
   g_object_class_install_property (gobject_class,
diff --git a/gio/gdbusserver.c b/gio/gdbusserver.c
index c43ceb7da..3fdded58a 100644
--- a/gio/gdbusserver.c
+++ b/gio/gdbusserver.c
@@ -320,7 +320,9 @@ g_dbus_server_class_init (GDBusServerClass *klass)
   /**
    * GDBusServer:guid:
    *
-   * The guid of the server.
+   * The GUID of the server.
+   *
+   * See #GDBusConnection:guid for more details.
    *
    * Since: 2.26
    */
diff --git a/gio/gdbusutils.c b/gio/gdbusutils.c
index bb34e2d58..4c6890f79 100644
--- a/gio/gdbusutils.c
+++ b/gio/gdbusutils.c
@@ -280,8 +280,14 @@ g_dbus_is_interface_name (const gchar *string)
  * Generate a D-Bus GUID that can be used with
  * e.g. g_dbus_connection_new().
  *
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * See the
+ * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids)
+ * regarding what strings are valid D-Bus GUIDs. The specification refers to
+ * these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as
+ * ‘GUIDs’. The terms are interchangeable.
+ *
+ * Note that D-Bus GUIDs do not follow
+ * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).
  *
  * Returns: A valid D-Bus GUID. Free with g_free().
  *
@@ -317,8 +323,8 @@ g_dbus_generate_guid (void)
  *
  * Checks if @string is a D-Bus GUID.
  *
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * See the documentation for g_dbus_generate_guid() for more information about
+ * the format of a GUID.
  *
  * Returns: %TRUE if @string is a guid, %FALSE otherwise.
  *