From 162371aa04401bf59e38059390d93c7002fb078b Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Fri, 12 Apr 2024 14:26:27 +0300
Subject: [PATCH] ; Fix documentation of a recent change in dbus.el (bug#70301)

* lisp/net/dbus.el (dbus-string-to-byte-array)
(dbus-byte-array-to-string):
* etc/NEWS:
* doc/misc/dbus.texi (Type Conversion): Fix documentation of these
two D-Bus functions.

(cherry picked from commit f93df59e8c9038a10992b71bfd6beeda70f806dd)
---
 doc/misc/dbus.texi |  9 +++++----
 etc/NEWS           | 12 +++++++++---
 lisp/net/dbus.el   |  7 ++++---
 3 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index c0a478d6ff6..e5d867acd40 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -1083,8 +1083,8 @@ elements of this array.  Example:
 
 @defun dbus-string-to-byte-array string
 Sometimes, D-Bus methods require as input parameter an array of bytes,
-instead of a string.  If it is guaranteed, that @var{string} is a
-UTF-8 string, this function performs the conversion.  Example:
+instead of a string.  This function converts @var{string} into an array
+of bytes of the UTF-8 encoding of @var{string}.  Example:
 
 @lisp
 (dbus-string-to-byte-array "/etc/hosts")
@@ -1156,8 +1156,9 @@ The signal @code{PropertyModified}, discussed as an example in
 
 @defun dbus-byte-array-to-string byte-array
 If a D-Bus method or signal returns an array of bytes, which are known
-to represent a UTF-8 string, this function converts @var{byte-array}
-to the corresponding UTF-8 string.  Example:
+to represent a UTF-8 string, this function converts @var{byte-array} to
+the corresponding Lisp string.  The contents of @var{byte-array} should
+be the byte sequence of a UTF-8 encoded string.  Example:
 
 @lisp
 (dbus-byte-array-to-string '(47 101 116 99 47 104 111 115 116 115))
diff --git a/etc/NEWS b/etc/NEWS
index e77654e7495..3023657e754 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1892,9 +1892,15 @@ of Emacs, for consistency with the common Emacs behavior where
 minibuffer history is reserved for past minibuffer inputs.
 
 +++
-** 'dbus-{string-to-byte-array,byte-array-to-string}' are strict UTF-8 conform.
-Both work over UTF-8 raw bytes only.  The optional parameter MULTIBYTE
-of 'dbus-byte-array-to-string' is obsolete now.
+** Conversion of strings to and from byte-arrays works with multibyte strings.
+The functions 'dbus-string-to-byte-array' and
+'dbus-byte-array-to-string}' now accept and return multibyte Lisp
+strings, encoding to UTF-8 and decoding from UTF-8 internally.  This
+means that the argument to 'dbus-byte-array-to-string' must be a valid
+UTF-8 byte sequence, and the optional parameter MULTIBYTE of
+'dbus-byte-array-to-string' is now obsolete and unused.  The argument of
+'dbus-string-to-byte-array' should be a regular Lisp string, not a
+unibyte string.
 
 
 * Lisp Changes in Emacs 30.1
diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 31a5eae5182..dd5f0e88859 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -995,7 +995,7 @@ association to the service from D-Bus."
 (defun dbus-string-to-byte-array (string)
   "Transform STRING to list (:array :byte C1 :byte C2 ...).
 The resulting byte array contains the raw bytes of the UTF-8 encoded
-STRING.."
+STRING."
   (if (length= string 0)
       '(:array :signature "y")
     (cons :array
@@ -1004,9 +1004,10 @@ STRING.."
                     (encode-coding-string string 'utf-8 'nocopy))))))
 
 (defun dbus-byte-array-to-string (byte-array &optional _multibyte)
-  "Transform BYTE-ARRAY into UTF-8 coded string.
+  "Transform BYTE-ARRAY with UTF-8 byte sequence into a string.
 BYTE-ARRAY must be a list of structure (c1 c2 ...), or a byte array as
-produced by `dbus-string-to-byte-array'."
+produced by `dbus-string-to-byte-array', and the individual bytes must
+be a valid UTF-8 byte sequence."
   (declare (advertised-calling-convention (byte-array) "30.1"))
   (if-let ((bytes (seq-filter #'characterp byte-array))
            (string (apply #'unibyte-string bytes)))
-- 
2.39.5