; 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)

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index c0a478d6ff6b4cbdaddd0b902d2364070a879368..e5d867acd407498097ee0ee35fa07793a610934b 100644 (file)
--- 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 e77654e749516a3f95fd0226bd0322f24fffe383..3023657e7540ae3d0489b5360d5a375b297cdb5e 100644 (file)
--- 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.
 
 \f
 * Lisp Changes in Emacs 30.1

diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 31a5eae51821d7aca6b3a468de1820e3fb08c9df..dd5f0e888596b1137221f23992931f34996da8d3 100644 (file)
--- 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)))