Subject: 27.0.91; Various D-Bus cleanups

From: "Basil L. Contovounesios" <[email-masked]>
Date: Sun, 07 Jun 2020 00:26:50 +0100

X-Debbugs-Cc: Michael Albinus <[email-masked]>
Severity: minor
Tags: patch

While reading through the D-Bus manual and implementation, I noticed
some opportunities for small cleanups.

I propose these documentation cleanups for emacs-27:

>From 962f2af23a0d71638e14bb143de866862d51d0d2 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <[email-masked]>
Date: Sat, 6 Jun 2020 00:58:37 +0100
Subject: [PATCH] Clean up D-Bus documentation

* doc/lispref/errors.texi (Standard Errors): The error symbol
dbus-error is defined even when Emacs is built without D-Bus.

* doc/misc/dbus.texi (Bus Names, Introspection)
(Nodes and Interfaces, Methods and Signal)
(Properties and Annotations, Arguments and Signatures)
(Synchronous Methods, Receiving Method Calls, Signals)
(Alternative Buses, Errors and Events): Clarify wording.  Fix
indentation of and simplify examples where possible.  Improve
Texinfo markup and cross-referencing where possible.
(Type Conversion): Ditto.  Remove mentions of Emacs' fixnum range
now that we have bignums.

* lisp/net/dbus.el (dbus-return-values-table)
(dbus-call-method-asynchronously, dbus-send-signal)
(dbus-register-signal, dbus-register-method)
(dbus-string-to-byte-array, dbus-byte-array-to-string)
(dbus-escape-as-identifier, dbus-check-event, dbus-event-bus-name)
(dbus-event-message-type, dbus-event-serial-number)
(dbus-event-service-name, dbus-event-path-name)
(dbus-event-interface-name, dbus-event-member-name)
(dbus-list-activatable-names, dbus-list-queued-owners, dbus-ping)
(dbus-introspect-get-interface-names, dbus-introspect-get-interface)
(dbus-introspect-get-method, dbus-introspect-get-signal)
(dbus-introspect-get-property, dbus-introspect-get-annotation-names)
(dbus-introspect-get-annotation, dbus-introspect-get-argument-names)
(dbus-introspect-get-argument, dbus-introspect-get-signature)
(dbus-set-property, dbus-register-property)
(dbus-get-all-managed-objects, dbus-init-bus): Clarify docstring and
improve formatting where possible.
(dbus-call-method): Ditto.  Remove mentions of Emacs' fixnum range
now that we have bignums.
---
 doc/lispref/errors.texi |   5 +-
 doc/misc/dbus.texi      | 795 ++++++++++++++++++++--------------------
 lisp/net/dbus.el        | 228 ++++++------
 3 files changed, 511 insertions(+), 517 deletions(-)

diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index dc6877c9ec..cd8694be8a 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -79,9 +79,8 @@ Standard Errors
 a loop}.  @xref{Variable Aliases}.
 
 @item dbus-error
-The message is @samp{D-Bus error}.  This is only defined if Emacs was
-compiled with D-Bus support.  @xref{Errors and Events,,, dbus, D-Bus
-integration in Emacs}.
+The message is @samp{D-Bus error}.  @xref{Errors and Events,,, dbus,
+D-Bus integration in Emacs}.
 
 @item end-of-buffer
 The message is @samp{End of buffer}.  @xref{Character Motion}.
diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 9e5f1ccc6f..eaf77ffa8f 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -167,7 +167,7 @@ Bus names
 described in a service registration file.  Under GNU/Linux, such files
 are located at @file{/usr/share/dbus-1/system-services/} (for the
 @code{:system} bus) or @file{/usr/share/dbus-1/services/}.  An
-activatable service is not necessarily registered at @var{bus} at already.
+activatable service is not necessarily registered at @var{bus} already.
 
 The result is a list of strings, which is @code{nil} when there are no
 activatable service names at all.  Example:
@@ -180,8 +180,8 @@ Bus names
 @end defun
 
 @defun dbus-list-names bus
-All service names, which are registered at D-Bus @var{bus}, are
-returned.  The result is a list of strings, which is @code{nil} when
+This function returns all service names, which are registered at D-Bus
+@var{bus}.  The result is a list of strings, which is @code{nil} when
 there are no registered service names at all.  Well known names are
 strings like @samp{org.freedesktop.DBus}.  Names starting with
 @samp{:} are unique names for services.
@@ -191,10 +191,10 @@ Bus names
 @end defun
 
 @defun dbus-list-known-names bus
-Retrieves all registered services which correspond to a known name in @var{bus}.
-A service has a known name if it doesn't start with @samp{:}.  The
-result is a list of strings, which is @code{nil} when there are no
-known names at all.
+This function retrieves all registered services which correspond to a
+known name in @var{bus}.  A service has a known name if it doesn't
+start with @samp{:}.  The result is a list of strings, which is
+@code{nil} when there are no known names at all.
 
 @var{bus} must be either the symbol @code{:system} or the symbol
 @code{:session}.
@@ -202,9 +202,9 @@ Bus names
 
 @defun dbus-list-queued-owners bus service
 For a given service, registered at D-Bus @var{bus} under the name
-@var{service}, all queued unique names are returned.  The result is a
-list of strings, or @code{nil} when there are no queued names for
-@var{service} at all.
+@var{service}, this function returns all queued unique names.  The
+result is a list of strings, or @code{nil} when there are no queued
+names for @var{service} at all.
 
 @var{bus} must be either the symbol @code{:system} or the symbol
 @code{:session}.  @var{service} must be a known service name as
@@ -213,9 +213,9 @@ Bus names
 
 @defun dbus-get-name-owner bus service
 For a given service, registered at D-Bus @var{bus} under the name
-@var{service}, the unique name of the name owner is returned.  The
-result is a string, or @code{nil} when there exist no name owner of
-@var{service}.
+@var{service}, this function returns the unique name of the name
+owner.  The result is a string, or @code{nil} when there is no name
+owner of @var{service}.
 
 @var{bus} must be either the symbol @code{:system} or the symbol
 @code{:session}.  @var{service} must be a known service name as
@@ -223,26 +223,28 @@ Bus names
 @end defun
 
 @defun dbus-ping bus service &optional timeout
-Check whether the service name @var{service} is registered at D-Bus
-@var{bus}.  @var{service} might not have been started yet, it is
-autostarted if possible.  The result is either @code{t} or @code{nil}.
+This function checks whether the service name @var{service} is
+registered at D-Bus @var{bus}.  If @var{service} has not yet started,
+it is autostarted if possible.  The result is either @code{t} or
+@code{nil}.
 
 @var{bus} must be either the symbol @code{:system} or the symbol
 @code{:session}.  @var{service} must be a string.  @var{timeout}, a
 nonnegative integer, specifies the maximum number of milliseconds
-@code{dbus-ping} must return.  The default value is 25,000.  Example:
+before @code{dbus-ping} must return.  The default value is 25,000.
+Example:
 
 @lisp
 (message
-   "%s screensaver on board."
-   (cond
-     ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
-     ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
-     (t "No")))
+ "%s screensaver on board."
+ (cond
+  ((dbus-ping :session "org.gnome.ScreenSaver" 100) "Gnome")
+  ((dbus-ping :session "org.freedesktop.ScreenSaver" 100) "KDE")
+  (t "No")))
 @end lisp
 
-If it shall be checked whether @var{service} is already running
-without autostarting it, one shall apply
+To check whether @var{service} is already running without autostarting
+it, you can instead write:
 
 @lisp
 (member service (dbus-list-known-names bus))
@@ -250,8 +252,9 @@ Bus names
 @end defun
 
 @defun dbus-get-unique-name bus
-The unique name, under which Emacs is registered at D-Bus @var{bus},
-is returned as string.
+@anchor{dbus-get-unique-name}
+This function returns the unique name, under which Emacs is registered
+at D-Bus @var{bus}, as a string.
 
 @var{bus} must be either the symbol @code{:system} or the symbol
 @code{:session}.
@@ -380,8 +383,8 @@ Introspection
 
 @lisp
 (dbus-introspect
-  :system "org.freedesktop.Hal"
-  "/org/freedesktop/Hal/devices/computer")
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer")
 
 @result{} "<!DOCTYPE node PUBLIC
     "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
@@ -420,14 +423,14 @@ Introspection
 @end defun
 
 @defun dbus-introspect-xml bus service path
-This function has the same intention as function
+This function serves a similar purpose to the function
 @code{dbus-introspect}.  The returned value is a parsed XML tree,
 which can be used for further analysis.  Example:
 
 @lisp
 (dbus-introspect-xml
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main")
 
 @result{} (node ((name . "/org/freedesktop/xesam/searcher/main"))
      (interface ((name . "org.freedesktop.xesam.Search"))
@@ -435,31 +438,27 @@ Introspection
          (arg ((name . "search") (type . "s") (direction . "in")))
          (arg ((name . "hit_ids") (type . "au") (direction . "in")))
          (arg ((name . "fields") (type . "as") (direction . "in")))
-         (arg ((name . "hit_data") (type . "aav") (direction . "out")))
-       )
+         (arg ((name . "hit_data") (type . "aav") (direction . "out"))))
        @dots{}
        (signal ((name . "HitsAdded"))
          (arg ((name . "search") (type . "s")))
-         (arg ((name . "count") (type . "u")))
-       )
-     )
-     @dots{}
-   )
+         (arg ((name . "count") (type . "u")))))
+     @dots{})
 @end lisp
 @end defun
 
 @defun dbus-introspect-get-attribute object attribute
-It returns the @var{attribute} value of a D-Bus introspection
-@var{object}.  @var{object} can be every subtree of a parsed XML tree
-as retrieved with @code{dbus-introspect-xml}.  @var{attribute} must be
-a string according to the attribute names in the D-Bus specification.
-Example:
+This function returns the @var{attribute} value of a D-Bus
+introspection @var{object}.  The value of @var{object} can be any
+subtree of a parsed XML tree as retrieved with
+@code{dbus-introspect-xml}.  @var{attribute} must be a string
+according to the attribute names in the D-Bus specification.  Example:
 
 @lisp
 (dbus-introspect-get-attribute
-  (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
-    "/org/freedesktop/SystemToolsBackends/UsersConfig")
-  "name")
+ (dbus-introspect-xml :system "org.freedesktop.SystemToolsBackends"
+                      "/org/freedesktop/SystemToolsBackends/UsersConfig")
+ "name")
 
 @result{} "/org/freedesktop/SystemToolsBackends/UsersConfig"
 @end lisp
@@ -476,12 +475,12 @@ Nodes and Interfaces
 object paths and interfaces.
 
 @defun dbus-introspect-get-node-names bus service path
-All node names of @var{service} in D-Bus @var{bus} at object path
-@var{path} are returned as list of strings.  Example:
+This function returns all node names of @var{service} in D-Bus
+@var{bus} at object path @var{path} as a list of strings.  Example:
 
 @lisp
 (dbus-introspect-get-node-names
-  :session "org.gnome.seahorse" "/org/gnome/seahorse")
+ :session "org.gnome.seahorse" "/org/gnome/seahorse")
 
 @result{} ("crypto" "keys")
 @end lisp
@@ -512,9 +511,10 @@ Nodes and Interfaces
 @end defun
 
 @defun dbus-introspect-get-interface-names bus service path
-There will be returned a list strings of all interface names of
+This function returns a list strings of all interface names of
 @var{service} in D-Bus @var{bus} at object path @var{path}.  This list
-will contain the default interface @samp{org.freedesktop.DBus.Introspectable}.
+will contain the default interface
+@samp{org.freedesktop.DBus.Introspectable}.
 
 Another default interface is @samp{org.freedesktop.DBus.Properties}.
 If present, @code{interface} elements can also have @code{property}
@@ -522,8 +522,8 @@ Nodes and Interfaces
 
 @lisp
 (dbus-introspect-get-interface-names
-  :system "org.freedesktop.Hal"
-  "/org/freedesktop/Hal/devices/computer")
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer")
 
 @result{} ("org.freedesktop.DBus.Introspectable"
     "org.freedesktop.Hal.Device"
@@ -533,30 +533,27 @@ Nodes and Interfaces
 @end defun
 
 @defun dbus-introspect-get-interface bus service path interface
-Return @var{interface} of @var{service} in D-Bus @var{bus} at object
-path @var{path}.  The return value is an XML element.  @var{interface}
-must be a string, element of the list returned by
-@code{dbus-introspect-get-interface-names}.  Example:
+This function returns @var{interface} of @var{service} in D-Bus
+@var{bus} at object path @var{path}.  The return value is an XML
+element.  @var{interface} must be a string and a member of the list
+returned by @code{dbus-introspect-get-interface-names}.  Example:
 
 @lisp
 (dbus-introspect-get-interface
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search")
 
 @result{} (interface ((name . "org.freedesktop.xesam.Search"))
      (method ((name . "GetHitData"))
        (arg ((name . "search") (type . "s") (direction . "in")))
        (arg ((name . "hit_ids") (type . "au") (direction . "in")))
        (arg ((name . "fields") (type . "as") (direction . "in")))
-       (arg ((name . "hit_data") (type . "aav") (direction . "out")))
-     )
+       (arg ((name . "hit_data") (type . "aav") (direction . "out"))))
      @dots{}
      (signal ((name . "HitsAdded"))
        (arg ((name . "search") (type . "s")))
-       (arg ((name . "count") (type . "u")))
-     )
-   )
+       (arg ((name . "count") (type . "u")))))
 @end lisp
 @end defun
 
@@ -565,7 +562,8 @@ Nodes and Interfaces
 data from a running system:
 
 @lisp
-(with-current-buffer (switch-to-buffer "*introspect*")
+(progn
+  (pop-to-buffer "*introspect*")
   (erase-buffer)
   (dolist (service (dbus-list-known-names :session))
     (dolist (path (dbus-introspect-get-all-nodes :session service "/"))
@@ -574,7 +572,7 @@ Nodes and Interfaces
       (when (delete
              "org.freedesktop.DBus.Introspectable"
              (dbus-introspect-get-interface-names :session service path))
-        (insert (message "\nservice: \"%s\" path: \"%s\"\n" service path)
+        (insert (format "\nservice: \"%s\" path: \"%s\"\n" service path)
                 (dbus-introspect :session service path))
         (redisplay t)))))
 @end lisp
@@ -587,14 +585,15 @@ Methods and Signal
 following functions return their specifications.
 
 @defun dbus-introspect-get-method-names bus service path interface
-Return a list of strings of all method names of @var{interface} of
-@var{service} in D-Bus @var{bus} at object path @var{path}.  Example:
+This function returns a list of strings of all method names of
+@var{interface} of @var{service} in D-Bus @var{bus} at object path
+@var{path}.  Example:
 
 @lisp
 (dbus-introspect-get-method-names
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search")
 
 @result{} ("GetState" "StartSearch" "GetHitCount" "GetHits" "NewSession"
     "CloseSession" "GetHitData" "SetProperty" "NewSearch"
@@ -603,35 +602,36 @@ Methods and Signal
 @end defun
 
 @defun dbus-introspect-get-method bus service path interface method
-This function returns @var{method} of @var{interface} as XML element.
-It must be located at @var{service} in D-Bus @var{bus} at object path
-@var{path}.  @var{method} must be a string, element of the list
-returned by @code{dbus-introspect-get-method-names}.  Example:
+This function returns @var{method} of @var{interface} as an XML
+element.  It must be located at @var{service} in D-Bus @var{bus} at
+object path @var{path}.  @var{method} must be a string and a member of
+the list returned by @code{dbus-introspect-get-method-names}.
+Example:
 
 @lisp
 (dbus-introspect-get-method
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search" "GetHitData")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData")
 
 @result{} (method ((name . "GetHitData"))
      (arg ((name . "search") (type . "s") (direction . "in")))
      (arg ((name . "hit_ids") (type . "au") (direction . "in")))
      (arg ((name . "fields") (type . "as") (direction . "in")))
-     (arg ((name . "hit_data") (type . "aav") (direction . "out")))
-   )
+     (arg ((name . "hit_data") (type . "aav") (direction . "out"))))
 @end lisp
 @end defun
 
 @defun dbus-introspect-get-signal-names bus service path interface
-Return a list of strings of all signal names of @var{interface} of
-@var{service} in D-Bus @var{bus} at object path @var{path}.  Example:
+This function returns a list of strings of all signal names of
+@var{interface} of @var{service} in D-Bus @var{bus} at object path
+@var{path}.  Example:
 
 @lisp
 (dbus-introspect-get-signal-names
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search")
 
 @result{} ("StateChanged" "SearchDone" "HitsModified"
     "HitsRemoved" "HitsAdded")
@@ -639,21 +639,21 @@ Methods and Signal
 @end defun
 
 @defun dbus-introspect-get-signal bus service path interface signal
-This function returns @var{signal} of @var{interface} as XML element.
-It must be located at @var{service} in D-Bus @var{bus} at object path
-@var{path}.  @var{signal} must be a string, element of the list
-returned by @code{dbus-introspect-get-signal-names}.  Example:
+This function returns @var{signal} of @var{interface} as an XML
+element.  It must be located at @var{service} in D-Bus @var{bus} at
+object path @var{path}.  @var{signal} must be a string and a member of
+the list returned by @code{dbus-introspect-get-signal-names}.
+Example:
 
 @lisp
 (dbus-introspect-get-signal
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search" "HitsAdded")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "HitsAdded")
 
 @result{} (signal ((name . "HitsAdded"))
      (arg ((name . "search") (type . "s")))
-     (arg ((name . "count") (type . "u")))
-   )
+     (arg ((name . "count") (type . "u"))))
 @end lisp
 @end defun
 
@@ -664,8 +664,8 @@ Properties and Annotations
 Interfaces can have properties.  These can be exposed via the
 @samp{org.freedesktop.DBus.Properties} interface@footnote{See
 @uref{https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties}}.
-That is, properties can be retrieved and changed during lifetime of an
-element.
+That is, properties can be retrieved and changed during the lifetime
+of an element.
 
 A generalized interface is
 @samp{org.freedesktop.DBus.Objectmanager}@footnote{See
@@ -678,13 +678,14 @@ Properties and Annotations
 the interface for a given language binding.
 
 @defun dbus-introspect-get-property-names bus service path interface
-Return a list of strings with all property names of @var{interface} of
-@var{service} in D-Bus @var{bus} at object path @var{path}.  Example:
+This function returns a list of strings with all property names of
+@var{interface} of @var{service} in D-Bus @var{bus} at object path
+@var{path}.  Example:
 
 @lisp
 (dbus-introspect-get-property-names
-  :session "org.kde.kded" "/modules/networkstatus"
-  "org.kde.Solid.Networking.Client")
+ :session "org.kde.kded" "/modules/networkstatus"
+ "org.kde.Solid.Networking.Client")
 
 @result{} ("Status")
 @end lisp
@@ -694,26 +695,26 @@ Properties and Annotations
 @end defun
 
 @defun dbus-introspect-get-property bus service path interface property
-This function returns @var{property} of @var{interface} as XML element.
-It must be located at @var{service} in D-Bus @var{bus} at object path
-@var{path}.  @var{property} must be a string, element of the list
-returned by @code{dbus-introspect-get-property-names}.
+This function returns @var{property} of @var{interface} as an XML
+element.  It must be located at @var{service} in D-Bus @var{bus} at
+object path @var{path}.  @var{property} must be a string and a member
+of the list returned by @code{dbus-introspect-get-property-names}.
 
 A @var{property} value can be retrieved by the function
 @code{dbus-introspect-get-attribute}.  Example:
 
 @lisp
 (dbus-introspect-get-property
-  :session "org.kde.kded" "/modules/networkstatus"
-  "org.kde.Solid.Networking.Client" "Status")
+ :session "org.kde.kded" "/modules/networkstatus"
+ "org.kde.Solid.Networking.Client" "Status")
 
 @result{} (property ((access . "read") (type . "u") (name . "Status")))
 
 (dbus-introspect-get-attribute
-  (dbus-introspect-get-property
-    :session "org.kde.kded" "/modules/networkstatus"
-    "org.kde.Solid.Networking.Client" "Status")
-  "access")
+ (dbus-introspect-get-property
+  :session "org.kde.kded" "/modules/networkstatus"
+  "org.kde.Solid.Networking.Client" "Status")
+ "access")
 
 @result{} "read"
 @end lisp
@@ -727,23 +728,23 @@ Properties and Annotations
 
 @lisp
 (dbus-get-property
-  :session "org.kde.kded" "/modules/networkstatus"
-  "org.kde.Solid.Networking.Client" "Status")
+ :session "org.kde.kded" "/modules/networkstatus"
+ "org.kde.Solid.Networking.Client" "Status")
 
 @result{} 4
 @end lisp
 @end defun
 
 @defun dbus-set-property bus service path interface property value
-Set value of @var{property} of @var{interface} to @var{value}.  It
-will be checked at @var{bus}, @var{service}, @var{path}.  When the
-value has been set successful, the result is @var{value}.  Otherwise,
-@code{nil} is returned.  Example:
+This function sets the value of @var{property} of @var{interface} to
+@var{value}.  It will be checked at @var{bus}, @var{service},
+@var{path}.  When the value is successfully set, this function returns
+@var{value}.  Otherwise, it returns @code{nil}.  Example:
 
 @lisp
 (dbus-set-property
-  :session "org.kde.kaccess" "/MainApplication"
-  "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
+ :session "org.kde.kaccess" "/MainApplication"
+ "com.trolltech.Qt.QApplication" "doubleClickInterval" 500)
 
 @result{} 500
 @end lisp
@@ -757,8 +758,8 @@ Properties and Annotations
 
 @lisp
 (dbus-get-all-properties
-  :session "org.kde.kaccess" "/MainApplication"
-  "com.trolltech.Qt.QApplication")
+ :session "org.kde.kaccess" "/MainApplication"
+ "com.trolltech.Qt.QApplication")
 
 @result{} (("cursorFlashTime" . 1000) ("doubleClickInterval" . 500)
     ("keyboardInputInterval" . 400) ("wheelScrollLines" . 3)
@@ -773,13 +774,13 @@ Properties and Annotations
 @var{path}, and the children of @var{path}.  The result is a list of
 objects.  Every object is a cons of an existing path name, and the
 list of available interface objects.  An interface object is another
-cons, which car is the interface name, and the cdr is the list of
+cons, whose car is the interface name and cdr is the list of
 properties as returned by @code{dbus-get-all-properties} for that path
-and interface. Example:
+and interface.  Example:
 
 @lisp
 (dbus-get-all-managed-objects
-  :session "org.gnome.SettingsDaemon" "/")
+ :session "org.gnome.SettingsDaemon" "/")
 
 @result{} (("/org/gnome/SettingsDaemon/MediaKeys"
      ("org.gnome.SettingsDaemon.MediaKeys")
@@ -809,31 +810,28 @@ Properties and Annotations
 properties could be retrieved by the following code:
 
 @lisp
-(with-current-buffer (switch-to-buffer "*objectmanager*")
+(let ((result (mapcar (lambda (service)
+                        (cons service
+                              (dbus-get-all-managed-objects
+                               :session service "/")))
+                      (dbus-list-known-names :session))))
+  (pop-to-buffer "*objectmanager*")
   (erase-buffer)
-  (let (result)
-    (dolist (service (dbus-list-known-names :session) result)
-      (message "%s" service)
-      (add-to-list
-       'result
-       (cons service
-             (dbus-get-all-managed-objects :session service "/"))))
-    (insert (message "%s" (pp result)))
-    (redisplay t)))
+  (pp result (current-buffer)))
 @end lisp
 @end defun
 
 @defun dbus-introspect-get-annotation-names bus service path interface &optional name
-Return a list of all annotation names as list of strings.  If
-@var{name} is @code{nil}, the annotations are children of
+This function returns a list of all annotation names as list of
+strings.  If @var{name} is @code{nil}, the annotations are children of
 @var{interface}, otherwise @var{name} must be a @code{method},
 @code{signal}, or @code{property} XML element, where the annotations
 belong to.  Example:
 
 @lisp
 (dbus-introspect-get-annotation-names
-  :session "de.berlios.Pinot" "/de/berlios/Pinot"
-  "de.berlios.Pinot" "GetStatistics")
+ :session "de.berlios.Pinot" "/de/berlios/Pinot"
+ "de.berlios.Pinot" "GetStatistics")
 
 @result{} ("de.berlios.Pinot.GetStatistics")
 @end lisp
@@ -855,29 +853,30 @@ Properties and Annotations
 @end defun
 
 @defun dbus-introspect-get-annotation bus service path interface name annotation
-Return annotation @var{ANNOTATION} as XML object.  If @var{name} is
-@code{nil}, @var{ANNOTATION} is a child of @var{interface}, otherwise
-@var{name} must be the name of a @code{method}, @code{signal}, or
-@code{property} XML element, where the @var{ANNOTATION} belongs to.
+This function returns @var{annotation} as an XML object.  If
+@var{name} is @code{nil}, @var{annotation} is a child of
+@var{interface}, otherwise @var{name} must be the name of a
+@code{method}, @code{signal}, or @code{property} XML element, where
+the @var{annotation} belongs to.
 
 An attribute value can be retrieved by
 @code{dbus-introspect-get-attribute}.  Example:
 
 @lisp
 (dbus-introspect-get-annotation
-  :session "de.berlios.Pinot" "/de/berlios/Pinot"
-  "de.berlios.Pinot" "GetStatistics"
-  "de.berlios.Pinot.GetStatistics")
+ :session "de.berlios.Pinot" "/de/berlios/Pinot"
+ "de.berlios.Pinot" "GetStatistics"
+ "de.berlios.Pinot.GetStatistics")
 
 @result{} (annotation ((name . "de.berlios.Pinot.GetStatistics")
                 (value . "pinotDBus")))
 
 (dbus-introspect-get-attribute
-  (dbus-introspect-get-annotation
-    :session "de.berlios.Pinot" "/de/berlios/Pinot"
-    "de.berlios.Pinot" "GetStatistics"
-    "de.berlios.Pinot.GetStatistics")
-  "value")
+ (dbus-introspect-get-annotation
+  :session "de.berlios.Pinot" "/de/berlios/Pinot"
+  "de.berlios.Pinot" "GetStatistics"
+  "de.berlios.Pinot.GetStatistics")
+ "value")
 
 @result{} "pinotDBus"
 @end lisp
@@ -891,39 +890,41 @@ Arguments and Signatures
 @code{arg} XML elements.
 
 @defun dbus-introspect-get-argument-names bus service path interface name
-Return a list of all argument names as list of strings.  @var{name}
-must be a @code{method} or @code{signal} XML element.  Example:
+This function returns a list of all argument names as strings.
+@var{name} must be a @code{method} or @code{signal} XML element.
+Example:
 
 @lisp
 (dbus-introspect-get-argument-names
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search" "GetHitData")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData")
 
 @result{} ("search" "hit_ids" "fields" "hit_data")
 @end lisp
 
-Argument names are optional; the function can return @code{nil}
-therefore, even if the method or signal has arguments.
+Argument names are optional; the function can therefore return
+@code{nil}, even if the method or signal has arguments.
 @end defun
 
 @defun dbus-introspect-get-argument bus service path interface name arg
-Return argument @var{ARG} as XML object.  @var{name}
-must be a @code{method} or @code{signal} XML element.  Example:
+This function returns the argument @var{arg} as an XML object.
+@var{name} must be a @code{method} or @code{signal} XML element.
+Example:
 
 @lisp
 (dbus-introspect-get-argument
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search" "GetHitData" "search")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData" "search")
 
 @result{} (arg ((name . "search") (type . "s") (direction . "in")))
 @end lisp
 @end defun
 
 @defun dbus-introspect-get-signature bus service path interface name &optional direction
-Return signature of a @code{method} or @code{signal}, represented by
-@var{name}, as string.
+This function returns the signature of a @code{method} or
+@code{signal}, represented by @var{name}, as a string.
 
 If @var{name} is a @code{method}, @var{direction} can be either
 @samp{in} or @samp{out}.  If @var{direction} is @code{nil}, @samp{in}
@@ -934,16 +935,16 @@ Arguments and Signatures
 
 @lisp
 (dbus-introspect-get-signature
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search" "GetHitData" "in")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "GetHitData" "in")
 
 @result{} "sauas"
 
 (dbus-introspect-get-signature
-  :session "org.freedesktop.xesam.searcher"
-  "/org/freedesktop/xesam/searcher/main"
-  "org.freedesktop.xesam.Search" "HitsAdded")
+ :session "org.freedesktop.xesam.searcher"
+ "/org/freedesktop/xesam/searcher/main"
+ "org.freedesktop.xesam.Search" "HitsAdded")
 
 @result{} "su"
 @end lisp
@@ -998,30 +999,27 @@ Type Conversion
 Example:
 
 @lisp
-(dbus-call-method @dots{} @var{NAT-NUMBER} @var{STRING})
+(dbus-call-method @dots{} @var{nat-number} @var{string})
 @end lisp
 
 is equivalent to
 
 @lisp
-(dbus-call-method @dots{} :uint32 @var{NAT-NUMBER} :string @var{STRING})
+(dbus-call-method @dots{} :uint32 @var{nat-number} :string @var{string})
 @end lisp
 
 but different to
 
 @lisp
-(dbus-call-method @dots{} :int32 @var{NAT-NUMBER} :signature @var{STRING})
+(dbus-call-method @dots{} :int32 @var{nat-number} :signature @var{string})
 @end lisp
 
 The value for a byte D-Bus type can be any integer in the range 0
 through 255.  If a character is used as argument, modifiers
 represented outside this range are stripped off.  For example,
 @code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to
-@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}.
-
-Signed and unsigned integer D-Bus types expect a corresponding integer
-value.  If the value does not fit Emacs's integer range, it is also
-possible to use an equivalent floating point number.
+@code{:byte ?\C-x} or @code{:byte ?\M-\C-x}.  Signed and unsigned
+integer D-Bus types expect a corresponding integer value.
 
 A D-Bus compound type is always represented as a list.  The @sc{car}
 of this list can be the type symbol @code{:array}, @code{:variant},
@@ -1036,13 +1034,13 @@ Type Conversion
 @item An array must contain only elements of the same D-Bus type.  It
 can be empty.
 
-@item A variant must contain only one single element.
+@item A variant must contain only a single element.
 
-@item A dictionary entry must be element of an array, and it must
+@item A dictionary entry must be an element of an array, and it must
 contain only a key-value pair of two elements, with a basic D-Bus type
 key.
 
-@item There is no restriction for structs.
+@item There are no restrictions for structs.
 @end itemize
 
 If an empty array needs an element D-Bus type other than string, it
@@ -1052,27 +1050,27 @@ Type Conversion
 
 @lisp
 (dbus-call-method
-  :session "org.freedesktop.Notifications"
-  "/org/freedesktop/Notifications"
-  "org.freedesktop.Notifications" "Notify"
-  "GNU Emacs"                 ;; Application name.
-  0                           ;; No replacement of other notifications.
-  ""                          ;; No icon.
-  "Notification summary"      ;; Summary.
-  (format                     ;; Body.
-    "This is a test notification, raised from\n%S" (emacs-version))
-  '(:array)                   ;; No actions (empty array of strings).
-  '(:array :signature "@{sv@}") ;; No hints
-                              ;; (empty array of dictionary entries).
-  :int32 -1)                  ;; Default timeout.
+ :session "org.freedesktop.Notifications"
+ "/org/freedesktop/Notifications"
+ "org.freedesktop.Notifications" "Notify"
+ "GNU Emacs"                   ; Application name.
+ 0                             ; No replacement of other notifications.
+ ""                            ; No icon.
+ "Notification summary"        ; Summary.
+ (format                       ; Body.
+  "This is a test notification, raised from\n%S" (emacs-version))
+ '(:array)                     ; No actions (empty array of strings).
+ '(:array :signature "@{sv@}") ; No hints
+                               ; (empty array of dictionary entries).
+ :int32 -1)                    ; Default timeout.
 
 @result{} 3
 @end lisp
 
 @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 an
-UTF8 string, this function performs the conversion.  Example:
+instead of a string.  If it is guaranteed, that @var{string} is a
+UTF-8 string, this function performs the conversion.  Example:
 
 @lisp
 (dbus-string-to-byte-array "/etc/hosts")
@@ -1083,10 +1081,10 @@ Type Conversion
 @end defun
 
 @defun dbus-escape-as-identifier string
-Escape an arbitrary @var{string} so it follows the rules for a C
-identifier.  The escaped string can be used as object path component,
-interface element component, bus name component or member name in
-D-Bus.
+This function escapes an arbitrary @var{string} so it follows the
+rules for a C identifier.  The escaped string can be used as object
+path component, interface element component, bus name component or
+member name in D-Bus.
 
 The escaping consists of replacing all non-alphanumerics, and the
 first character if it's a digit, with an underscore and two
@@ -1107,18 +1105,18 @@ Type Conversion
 objects.
 
 @example
-@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number or float}
+@multitable {DBUS_TYPE_OBJECT_PATH} {@expansion{}} {natural number}
 @item D-Bus type            @tab              @tab Lisp type
 @item
 @item DBUS_TYPE_BOOLEAN     @tab @expansion{} @tab @code{t} or @code{nil}
 @item DBUS_TYPE_BYTE        @tab @expansion{} @tab natural number
 @item DBUS_TYPE_UINT16      @tab @expansion{} @tab natural number
 @item DBUS_TYPE_INT16       @tab @expansion{} @tab integer
-@item DBUS_TYPE_UINT32      @tab @expansion{} @tab natural number or float
-@item DBUS_TYPE_UNIX_FD     @tab @expansion{} @tab natural number or float
-@item DBUS_TYPE_INT32       @tab @expansion{} @tab integer or float
-@item DBUS_TYPE_UINT64      @tab @expansion{} @tab natural number or float
-@item DBUS_TYPE_INT64       @tab @expansion{} @tab integer or float
+@item DBUS_TYPE_UINT32      @tab @expansion{} @tab natural number
+@item DBUS_TYPE_UNIX_FD     @tab @expansion{} @tab natural number
+@item DBUS_TYPE_INT32       @tab @expansion{} @tab integer
+@item DBUS_TYPE_UINT64      @tab @expansion{} @tab natural number
+@item DBUS_TYPE_INT64       @tab @expansion{} @tab integer
 @item DBUS_TYPE_DOUBLE      @tab @expansion{} @tab float
 @item DBUS_TYPE_STRING      @tab @expansion{} @tab string
 @item DBUS_TYPE_OBJECT_PATH @tab @expansion{} @tab string
@@ -1130,26 +1128,21 @@ Type Conversion
 @end multitable
 @end example
 
-A float object in case of @code{DBUS_TYPE_UINT32},
-@code{DBUS_TYPE_INT32}, @code{DBUS_TYPE_UINT64},
-@code{DBUS_TYPE_INT64} and @code{DBUS_TYPE_UNIX_FD} is returned, when
-the C value exceeds the Emacs number size range.
-
 The resulting list of the last 4 D-Bus compound types contains as
 elements the elements of the D-Bus container, mapped according to the
 same rules.
 
-The signal @code{PropertyModified}, discussed as example in
+The signal @code{PropertyModified}, discussed as an example in
 @ref{Inspection}, would offer as Lisp data the following object
-(@var{BOOL} stands here for either @code{nil} or @code{t}):
+(@var{bool} stands here for either @code{nil} or @code{t}):
 
 @lisp
-(@var{INTEGER} ((@var{STRING} @var{BOOL} @var{BOOL}) (@var{STRING} @var{BOOL} @var{BOOL}) @dots{}))
+(@var{integer} ((@var{string} @var{bool} @var{bool}) (@var{string} @var{bool} @var{bool}) @dots{}))
 @end lisp
 
 @defun dbus-byte-array-to-string byte-array &optional multibyte
 If a D-Bus method or signal returns an array of bytes, which are known
-to represent an UTF8 string, this function converts @var{byte-array}
+to represent a UTF-8 string, this function converts @var{byte-array}
 to the corresponding string.  The string is unibyte encoded, unless
 @var{multibyte} is non-@code{nil}.  Example:
 
@@ -1161,9 +1154,9 @@ Type Conversion
 @end defun
 
 @defun dbus-unescape-from-identifier string
-Retrieve the original string from the encoded @var{string} as unibyte
-string.  @var{string} must have been encoded with
-@code{dbus-escape-as-identifier}.  Example:
+This function retrieves the original string from the encoded
+@var{string} as a unibyte string.  The value of @var{string} must have
+been encoded with @code{dbus-escape-as-identifier}.  Example:
 
 @lisp
 (dbus-unescape-from-identifier "_30123abc_5fxyz_01_ff")
@@ -1177,9 +1170,9 @@ Type Conversion
 
 @lisp
 (string-equal
-  (dbus-unescape-from-identifier
-    (dbus-escape-as-identifier "Grüß Göttin"))
-  "Grüß Göttin")
+ (dbus-unescape-from-identifier
+  (dbus-escape-as-identifier "Grüß Göttin"))
+ "Grüß Göttin")
 
 @result{} nil
 @end lisp
@@ -1196,12 +1189,13 @@ Synchronous Methods
 Methods can be called synchronously (@dfn{blocking}) or asynchronously
 (@dfn{non-blocking}).
 
-At D-Bus level, a method call consist of two messages: one message
+At the D-Bus level, a method call consist of two messages: one message
 which carries the input parameters to the object owning the method to
 be called, and a reply message returning the resulting output
 parameters from the object.
 
 @defun dbus-call-method bus service path interface method &optional :timeout timeout &rest args
+@anchor{dbus-call-method}
 This function calls @var{method} on the D-Bus @var{bus}.  @var{bus} is
 either the symbol @code{:system} or the symbol @code{:session}.
 
@@ -1210,14 +1204,14 @@ Synchronous Methods
 an interface offered by @var{service}.  It must provide @var{method}.
 
 If the parameter @code{:timeout} is given, the following integer
-@var{timeout} specifies the maximum number of milliseconds the method
-call must return.  The default value is 25,000.  If the method call
-doesn't return in time, a D-Bus error is raised (@pxref{Errors and
-Events}).
+@var{timeout} specifies the maximum number of milliseconds before the
+method call must return.  The default value is 25,000.  If the method
+call doesn't return in time, a D-Bus error is raised (@pxref{Errors
+and Events}).
 
-All other arguments args are passed to @var{method} as arguments.
-They are converted into D-Bus types as described in @ref{Type
-Conversion}.
+The remaining arguments @var{args} are passed to @var{method} as
+arguments.  They are converted into D-Bus types as described in
+@ref{Type Conversion}.
 
 The function returns the resulting values of @var{method} as a list of
 Lisp objects, according to the type conversion rules described in
@@ -1225,9 +1219,9 @@ Synchronous Methods
 
 @lisp
 (dbus-call-method
-  :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
-  "org.gnome.seahorse.Keys" "GetKeyField"
-  "openpgp:657984B8C7A966DD" "simple-name")
+ :session "org.gnome.seahorse" "/org/gnome/seahorse/keys/openpgp"
+ "org.gnome.seahorse.Keys" "GetKeyField"
+ "openpgp:657984B8C7A966DD" "simple-name")
 
 @result{} (t ("Philip R. Zimmermann"))
 @end lisp
@@ -1238,10 +1232,10 @@ Synchronous Methods
 
 @lisp
 (dbus-call-method
-  :system "org.freedesktop.Hal"
-  "/org/freedesktop/Hal/devices/computer"
-  "org.freedesktop.Hal.Device" "GetPropertyString"
-  "system.kernel.machine")
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer"
+ "org.freedesktop.Hal.Device" "GetPropertyString"
+ "system.kernel.machine")
 
 @result{} "i686"
 @end lisp
@@ -1257,17 +1251,17 @@ Synchronous Methods
 
 @lisp
 (dolist (device
-          (dbus-call-method
-            :system "org.freedesktop.Hal"
-            "/org/freedesktop/Hal/Manager"
-            "org.freedesktop.Hal.Manager" "GetAllDevices"))
+         (dbus-call-method
+          :system "org.freedesktop.Hal"
+          "/org/freedesktop/Hal/Manager"
+          "org.freedesktop.Hal.Manager" "GetAllDevices"))
   (message "\nudi = %s" device)
   (dolist (properties
-            (dbus-call-method
-              :system "org.freedesktop.Hal" device
-              "org.freedesktop.Hal.Device" "GetAllProperties"))
+           (dbus-call-method
+            :system "org.freedesktop.Hal" device
+            "org.freedesktop.Hal.Device" "GetAllProperties"))
     (message "  %s = %S"
-             (car properties) (or (caar (cdr properties)) ""))))
+             (car properties) (or (caadr properties) ""))))
 
 @print{} "udi = /org/freedesktop/Hal/devices/computer
       info.addons = (\"hald-addon-acpi\")
@@ -1304,34 +1298,35 @@ Asynchronous Methods
 an interface offered by @var{service}.  It must provide @var{method}.
 
 @var{handler} is a Lisp function, which is called when the
-corresponding return message has arrived.  If @var{handler} is
-@code{nil}, no return message will be expected.
+corresponding return message arrives.  If @var{handler} is @code{nil},
+no return message will be expected.
 
 If the parameter @code{:timeout} is given, the following integer
-@var{timeout} specifies the maximum number of milliseconds a reply
-message must arrive.  The default value is 25,000.  If there is no
-reply message in time, a D-Bus error is raised (@pxref{Errors and
+@var{timeout} specifies the maximum number of milliseconds before a
+reply message must arrive.  The default value is 25,000.  If there is
+no reply message in time, a D-Bus error is raised (@pxref{Errors and
 Events}).
 
-All other arguments args are passed to @var{method} as arguments.
-They are converted into D-Bus types as described in @ref{Type
-Conversion}.
+The remaining arguments @var{args} are passed to @var{method} as
+arguments.  They are converted into D-Bus types as described in
+@ref{Type Conversion}.
 
 If @var{handler} is a Lisp function, the function returns a key into
 the hash table @code{dbus-registered-objects-table}.  The
 corresponding entry in the hash table is removed, when the return
-message has been arrived, and @var{handler} is called.  Example:
+message arrives, and @var{handler} is called.  Example:
 
 @lisp
 (dbus-call-method-asynchronously
-  :system "org.freedesktop.Hal"
-  "/org/freedesktop/Hal/devices/computer"
-  "org.freedesktop.Hal.Device" "GetPropertyString" 'message
-  "system.kernel.machine")
-
-@result{} (:serial :system 2)
+ :system "org.freedesktop.Hal"
+ "/org/freedesktop/Hal/devices/computer"
+ "org.freedesktop.Hal.Device" "GetPropertyString"
+ (lambda (msg) (message "%s" msg))
+ "system.kernel.machine")
 
 @print{} i686
+
+@result{} (:serial :system 2)
 @end lisp
 @end defun
 
@@ -1347,7 +1342,8 @@ Receiving Method Calls
 the following functions:
 
 @defun dbus-register-service bus service &rest flags
-Register the known name @var{service} on D-Bus @var{bus}.
+This function registers the known name @var{service} on D-Bus
+@var{bus}.
 
 @var{bus} is either the symbol @code{:system} or the symbol
 @code{:session}.
@@ -1357,36 +1353,33 @@ Receiving Method Calls
 
 @var{flags} is a subset of the following keywords:
 
-@itemize
-@item @code{:allow-replacement}: Allow another service to become the primary
-owner if requested.
-
-@item @code{:replace-existing}: Request to replace the current primary owner.
-
-@item @code{:do-not-queue}: If we can not become the primary owner do not
-place us in the queue.
-@end itemize
+@table @code
+@item :allow-replacement
+Allow another service to become the primary owner if requested.
+@item :replace-existing
+Request to replace the current primary owner.
+@item :do-not-queue
+If we can not become the primary owner do not place us in the queue.
+@end table
 
 One of the following keywords is returned:
 
-@itemize
-
-@item @code{:primary-owner}: We have become the primary owner of the name
-@var{service}.
-
-@item @code{:in-queue}: We could not become the primary owner and
-have been placed in the queue.
-
-@item @code{:exists}: We already are in the queue.
-
-@item @code{:already-owner}: We already are the primary
-owner.
-@end itemize
+@table @code
+@item :primary-owner
+We have become the primary owner of the name @var{service}.
+@item :in-queue
+We could not become the primary owner and have been placed in the
+queue.
+@item :exists
+We already are in the queue.
+@item :already-owner
+We already are the primary owner.
+@end table
 @end defun
 
 @defun dbus-unregister-service bus service
-Unregister all objects from D-Bus @var{bus}, registered by Emacs for
-@var{service}.
+This function unregisters all objects from D-Bus @var{bus}, that were
+registered by Emacs for @var{service}.
 
 @var{bus} is either the symbol @code{:system} or the symbol
 @code{:session}.
@@ -1397,24 +1390,27 @@ Receiving Method Calls
 
 One of the following keywords is returned:
 
-@itemize
-@item @code{:released}: We successfully released the name @var{service}.
-@item @code{:non-existent}: The name @var{service} does not exist on the bus.
-@item @code{:not-owner}: We are not an owner of the name @var{service}.
-@end itemize
+@table @code
+@item :released
+We successfully released the name @var{service}.
+@item :non-existent
+The name @var{service} does not exist on the bus.
+@item :not-owner
+We are not an owner of the name @var{service}.
+@end table
 @end defun
 
-When a name has been chosen, Emacs can offer own methods, which can be
-called by other applications.  These methods could be an
+When a name has been chosen, Emacs can offer its own methods, which
+can be called by other applications.  These methods could be an
 implementation of an interface of a well known service, like
 @samp{org.freedesktop.TextEditor}.
 
-It could be also an implementation of an own interface.  In this case,
-the service name must be @samp{org.gnu.Emacs}.  The object path shall
-begin with @samp{/org/gnu/Emacs/@strong{Application}}, and the
-interface name shall be @code{org.gnu.Emacs.@strong{Application}}.
-@samp{@strong{Application}} is the name of the application which
-provides the interface.
+They could also be an implementation of its own interface.  In this
+case, the service name must be @samp{org.gnu.Emacs}.  The object path
+shall begin with @samp{/org/gnu/Emacs/@var{application}}, and the
+interface name shall be @code{org.gnu.Emacs.@var{application}}, where
+@var{application} is the name of the application which provides the
+interface.
 
 @deffn Constant dbus-service-emacs
 The well known service name @samp{org.gnu.Emacs} of Emacs.
@@ -1436,10 +1432,10 @@ Receiving Method Calls
 @code{:session}.
 
 @var{service} is the D-Bus service name of the D-Bus object
-@var{method} is registered for.  It must be a known name (See
+@var{method} is registered for.  It must be a known name (see
 discussion of @var{dont-register-service} below).
 
-@var{path} is the D-Bus object path @var{service} is registered (See
+@var{path} is the D-Bus object path @var{service} is registered (see
 discussion of @var{dont-register-service} below).
 
 @var{interface} is the interface offered by @var{service}.  It must
@@ -1456,8 +1452,8 @@ Receiving Method Calls
 cons cell, @var{handler} can return this object directly, instead of
 returning a list containing the object.
 
-In case @var{handler} shall return a reply message with an empty
-argument list, @var{handler} must return the symbol @code{:ignore}.
+If @var{handler} returns a reply message with an empty argument list,
+@var{handler} must return the symbol @code{:ignore}.
 
 When @var{dont-register-service} is non-@code{nil}, the known name
 @var{service} is not registered.  This means that other D-Bus clients
@@ -1468,7 +1464,7 @@ Receiving Method Calls
 
 The default D-Bus timeout when waiting for a message reply is 25
 seconds.  This value could be even smaller, depending on the calling
-client.  Therefore, @var{handler} shall not last longer than
+client.  Therefore, @var{handler} should not last longer than
 absolutely necessary.
 
 @code{dbus-register-method} returns a Lisp object, which can be used
@@ -1477,18 +1473,14 @@ Receiving Method Calls
 
 @lisp
 (defun my-dbus-method-handler (filename)
-  (let (result)
-    (if (find-file filename)
-        (setq result '(:boolean t))
-      (setq result '(:boolean nil)))
-    result))
-
-@result{} my-dbus-method-handler
+  (if (find-file filename)
+      '(:boolean t)
+    '(:boolean nil)))
 
 (dbus-register-method
-  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
-  "org.freedesktop.TextEditor" "OpenFile"
-  'my-dbus-method-handler)
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "OpenFile"
+ #'my-dbus-method-handler)
 
 @result{} ((:method :session "org.freedesktop.TextEditor" "OpenFile")
     ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
@@ -1496,9 +1488,9 @@ Receiving Method Calls
 @end lisp
 
 If you invoke the method @samp{org.freedesktop.TextEditor.OpenFile}
-from another D-Bus application with a filename as parameter, the file
+from another D-Bus application with a file name as parameter, the file
 is opened in Emacs, and the method returns either @var{true} or
-@var{false}, indicating the success of the method.  As test tool one
+@var{false}, indicating the success of the method.  As a test tool one
 could use the command line tool @code{dbus-send} in a shell:
 
 @example
@@ -1522,11 +1514,9 @@ Receiving Method Calls
       (find-file (car args))
     (error (signal 'dbus-error (cdr err))))
   t)
-
-@result{} my-dbus-method-handler
 @end lisp
 
-The test runs then
+The test then runs
 
 @example
 # dbus-send --session --print-reply \
@@ -1550,7 +1540,7 @@ Receiving Method Calls
 @var{service} is the D-Bus service name of the D-Bus.  It must be a
 known name.
 
-@var{path} is the D-Bus object path @var{service} is registered (See
+@var{path} is the D-Bus object path @var{service} is registered (see
 discussion of @var{dont-register-service} below).
 
 @var{interface} is the name of the interface used at @var{path},
@@ -1559,7 +1549,7 @@ Receiving Method Calls
 @var{access} indicates, whether the property can be changed by other
 services via D-Bus.  It must be either the symbol @code{:read} or
 @code{:readwrite}.  @var{value} is the initial value of the property,
-it can be of any valid type (see @code{dbus-call-method} for details).
+it can be of any valid type (@xref{dbus-call-method}, for details).
 
 If @var{property} already exists on @var{path}, it will be
 overwritten.  For properties with access type @code{:read} this is the
@@ -1584,15 +1574,15 @@ Receiving Method Calls
 
 @lisp
 (dbus-register-property
-  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
-  "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "name" :read "GNU Emacs")
 
 @result{} ((:property :session "org.freedesktop.TextEditor" "name")
     ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
 
 (dbus-register-property
-  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
-  "org.freedesktop.TextEditor" "version" :readwrite emacs-version t)
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "version" :readwrite emacs-version t)
 
 @result{} ((:property :session "org.freedesktop.TextEditor" "version")
     ("org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"))
@@ -1623,28 +1613,28 @@ Receiving Method Calls
       ]
 @end example
 
-It is also possible, to apply the @code{dbus-get-property},
+It is also possible to apply the @code{dbus-get-property},
 @code{dbus-get-all-properties} and @code{dbus-set-property} functions
 (@pxref{Properties and Annotations}).
 
 @lisp
 (dbus-set-property
-  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
-  "org.freedesktop.TextEditor" "version" "23.1.50")
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "version" "23.1.50")
 
 @result{} "23.1.50"
 
 (dbus-get-property
-  :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
-  "org.freedesktop.TextEditor" "version")
+ :session "org.freedesktop.TextEditor" "/org/freedesktop/TextEditor"
+ "org.freedesktop.TextEditor" "version")
 
 @result{} "23.1.50"
 @end lisp
 @end defun
 
 @defun dbus-unregister-object object
-Unregister @var{object} from the D-Bus.  @var{object} must be the
-result of a preceding @code{dbus-register-method},
+This function unregisters @var{object} from the D-Bus.  @var{object}
+must be the result of a preceding @code{dbus-register-method},
 @code{dbus-register-property} or @code{dbus-register-signal} call
 (@pxref{Signals}).  It returns @code{t} if @var{object} has been
 unregistered, @code{nil} otherwise.
@@ -1672,22 +1662,22 @@ Signals
 
 Signals can be unicast or broadcast messages.  For broadcast messages,
 @var{service} must be @code{nil}.  Otherwise, @var{service} is the
-D-Bus service name the signal is sent to as unicast
+D-Bus service name the signal is sent to as a unicast
 message.@footnote{For backward compatibility, a broadcast message is
 also emitted if @var{service} is the known or unique name Emacs is
 registered at D-Bus @var{bus}.}  @var{path} is the D-Bus object path
 @var{signal} is sent from.  @var{interface} is an interface available
 at @var{path}.  It must provide @var{signal}.
 
-All other arguments args are passed to @var{signal} as arguments.
-They are converted into D-Bus types as described in @ref{Type
-Conversion}.  Example:
+The remaining arguments @var{args} are passed to @var{signal} as
+arguments.  They are converted into D-Bus types as described in
+@ref{Type Conversion}.  Example:
 
 @lisp
 (dbus-send-signal
-  :session nil dbus-path-emacs
-  (concat dbus-interface-emacs ".FileManager") "FileModified"
-  "/home/albinus/.emacs")
+ :session nil dbus-path-emacs
+ (concat dbus-interface-emacs ".FileManager") "FileModified"
+ "/home/albinus/.emacs")
 @end lisp
 @end defun
 
@@ -1702,11 +1692,11 @@ Signals
 object.  It can be either a known name or the unique name of the D-Bus
 object sending the signal.  A known name will be mapped onto the
 unique name of the object, owning @var{service} at registration time.
-When the corresponding D-Bus object disappears, signals won't be
-received any longer.
+When the corresponding D-Bus object disappears, signals will no longer
+be received.
 
-@var{path} is the corresponding D-Bus object path, @var{service} is
-registered at.  @var{interface} is an interface offered by
+@var{path} is the corresponding D-Bus object path that @var{service}
+is registered at.  @var{interface} is an interface offered by
 @var{service}.  It must provide @var{signal}.
 
 @var{service}, @var{path}, @var{interface} and @var{signal} can be
@@ -1721,30 +1711,31 @@ Signals
 pairs.@footnote{For backward compatibility, the arguments @var{args}
 can also be just strings.  They stand for the respective arguments of
 @var{signal} in their order, and are used for filtering as well.  A
-@code{nil} argument might be used to preserve the order.}  The meaning
-is as follows:
+@code{nil} argument might be used to preserve the order.}  Their
+meaning is as follows:
 
-@itemize
-@item @code{:argN} @var{string}:@*
-@code{:pathN} @var{string}:@*
-This stands for the Nth argument of the signal.  @code{:pathN}
-arguments can be used for object path wildcard matches as specified by
-D-Bus, while an @code{:argN} argument requires an exact match.
+@table @code
+@item :arg@var{n} @var{string}
+@item :path@var{n} @var{string}
+This stands for the @var{n}th argument of the signal.
+@code{:path@var{n}} arguments can be used for object path wildcard
+matches as specified by D-Bus, while an @code{:argN} argument requires
+an exact match.
 
-@item @code{:arg-namespace} @var{string}:@*
-Register for the signals, which first argument defines the service or
-interface namespace @var{string}.
+@item :arg-namespace @var{string}
+Register for those signals, whose first argument names a service or
+interface within the namespace @var{string}.
 
-@item @code{:path-namespace} @var{string}:@*
+@item :path-namespace @var{string}
 Register for the object path namespace @var{string}.  All signals sent
 from an object path, which has @var{string} as the preceding string,
 are matched.  This requires @var{path} to be @code{nil}.
 
-@item @code{:eavesdrop}:@*
+@item :eavesdrop
 Register for unicast signals which are not directed to the D-Bus
 object Emacs is registered at D-Bus BUS, if the security policy of BUS
 allows this.  Otherwise, this argument is ignored.
-@end itemize
+@end table
 
 @code{dbus-register-signal} returns a Lisp object, which can be used
 as argument in @code{dbus-unregister-object} for removing the
@@ -1754,12 +1745,10 @@ Signals
 (defun my-dbus-signal-handler (device)
   (message "Device %s added" device))
 
-@result{} my-dbus-signal-handler
-
 (dbus-register-signal
-  :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
-  "org.freedesktop.Hal.Manager" "DeviceAdded"
-  'my-dbus-signal-handler)
+ :system "org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
+ "org.freedesktop.Hal.Manager" "DeviceAdded"
+ #'my-dbus-signal-handler)
 
 @result{} ((:signal :system "org.freedesktop.Hal.Manager" "DeviceAdded")
     ("org.freedesktop.Hal" "/org/freedesktop/Hal/Manager"
@@ -1769,8 +1758,8 @@ Signals
 As we know from the introspection data of interface
 @samp{org.freedesktop.Hal.Manager}, the signal @samp{DeviceAdded}
 provides one single parameter, which is mapped into a Lisp string.
-The callback function @code{my-dbus-signal-handler} must define one
-single string argument therefore.  Plugging an USB device to your
+The callback function @code{my-dbus-signal-handler} must therefore
+define a single string argument.  Plugging a USB device into your
 machine, when registered for signal @samp{DeviceAdded}, will show you
 which objects the GNU/Linux @code{hal} daemon adds.
 
@@ -1781,7 +1770,7 @@ Signals
 @lisp
 (dbus-ignore-errors
   (dbus-register-signal
-    :system nil nil nil nil 'ignore :path-namespace "/invalid/path"))
+   :system nil nil nil nil #'ignore :path-namespace "/invalid/path"))
 
 @result{} nil
 @end lisp
@@ -1796,14 +1785,14 @@ Alternative Buses
 
 Until now, we have spoken about the system and the session buses,
 which are the default buses to be connected to.  However, it is
-possible to connect to any bus, from which the address is known.  This
-is a UNIX domain or TCP/IP socket.  Everywhere, where a @var{bus} is
-mentioned as argument of a function (the symbol @code{:system} or the
-symbol @code{:session}), this address can be used instead.  The
-connection to this bus must be initialized first.
+possible to connect to any bus with a known address.  This is a UNIX
+domain or TCP/IP socket.  Everywhere, where a @var{bus} is mentioned
+as argument of a function (the symbol @code{:system} or the symbol
+@code{:session}), this address can be used instead.  The connection to
+this bus must be initialized first.
 
 @defun dbus-init-bus bus &optional private
-Establish the connection to D-Bus @var{bus}.
+This function establishes the connection to D-Bus @var{bus}.
 
 @var{bus} can be either the symbol @code{:system} or the symbol
 @code{:session}, or it can be a string denoting the address of the
@@ -1811,12 +1800,12 @@ Alternative Buses
 is called when loading @file{dbus.el}, there is no need to call it
 again.
 
-The function returns a number, which counts the connections this Emacs
-session has established to the @var{bus} under the same unique name
-(see @code{dbus-get-unique-name}).  It depends on the libraries Emacs
-is linked with, and on the environment Emacs is running.  For example,
-if Emacs is linked with the GTK+ toolkit, and it runs in a GTK+-aware
-environment like Gnome, another connection might already be
+The function returns the number of connections this Emacs session has
+established to the @var{bus} under the same unique name
+(@pxref{dbus-get-unique-name}).  It depends on the libraries Emacs is
+linked with, and on the environment Emacs is running.  For example, if
+Emacs is linked with the GTK+ toolkit, and it runs in a GTK+-aware
+environment like GNOME, another connection might already be
 established.
 
 When @var{private} is non-@code{nil}, a new connection is established
@@ -1831,9 +1820,9 @@ Alternative Buses
 
 @lisp
 (setq my-bus
-  (dbus-call-method
-   :session "org.a11y.Bus" "/org/a11y/bus"
-   "org.a11y.Bus" "GetAddress"))
+      (dbus-call-method
+       :session "org.a11y.Bus" "/org/a11y/bus"
+       "org.a11y.Bus" "GetAddress"))
 
 @result{} "unix:abstract=/tmp/dbus-2yzWHOCdSD,guid=a490dd26625870ca1298b6e10000fd7f"
 
@@ -1848,7 +1837,7 @@ Alternative Buses
 
 @result{} ":1.19"
 
-;; Open a new connection to the same bus.  This obsoletes the
+;; Open a new connection to the same bus.  This supersedes the
 ;; previous one.
 (dbus-init-bus my-bus 'private)
 
@@ -1859,14 +1848,14 @@ Alternative Buses
 @result{} ":1.20"
 @end lisp
 
-D-Bus addresses can specify different transport.  A possible address
-could be based on TCP/IP sockets, see next example.  However, it
-depends on the bus daemon configuration, which transport is supported.
+D-Bus addresses can specify a different transport.  A possible address
+could be based on TCP/IP sockets, see next example.  Which transport
+is supported depends on the bus daemon configuration, however.
 @end defun
 
 @defun dbus-setenv bus variable value
-Set the value of the @var{bus} environment variable @var{variable} to
-@var{value}.
+This function sets the value of the @var{bus} environment
+@var{variable} to @var{value}.
 
 @var{bus} is either a Lisp symbol, @code{:system} or @code{:session},
 or a string denoting the bus address.  Both @var{variable} and
@@ -1877,7 +1866,7 @@ Alternative Buses
 
 Some bus instances, such as @code{:system}, may disable setting the
 environment.  In such cases, or if this feature is not available in
-older D-Bus versions, a @code{dbus-error} error is raised.
+older D-Bus versions, this function signals a @code{dbus-error}.
 
 As an example, it might be desirable to start X11 enabled services on
 a remote host's bus on the same X11 server the local Emacs is
@@ -1916,7 +1905,7 @@ Errors and Events
 @code{dbus-register-method}, @code{dbus-register-property} and
 @code{dbus-register-signal} are checked for correct D-Bus types. If
 there is a type mismatch, the Lisp error @code{wrong-type-argument}
-@code{D-Bus ARG} is raised.
+@code{D-Bus @var{arg}} is raised.
 
 All errors raised by D-Bus are signaled with the error symbol
 @code{dbus-error}.  If possible, error messages from D-Bus are
@@ -1967,35 +1956,39 @@ Errors and Events
 callback function in order to retrieve the information from the event.
 
 @defun dbus-event-bus-name event
-Returns the bus name @var{event} is coming from.
-The result is either the symbol @code{:system} or the symbol @code{:session}.
+This function returns the bus name @var{event} is coming from.  The
+result is either the symbol @code{:system} or the symbol
+@code{:session}.
 @end defun
 
 @defun dbus-event-message-type event
-Returns the message type of the corresponding D-Bus message.  The
-result is a natural number.
+This function returns the message type of the corresponding D-Bus
+message.  The result is a natural number.
 @end defun
 
 @defun dbus-event-serial-number event
-Returns the serial number of the corresponding D-Bus message.
-The result is a natural number.
+This function returns the serial number of the corresponding D-Bus
+message.  The result is a natural number.
 @end defun
 
 @defun dbus-event-service-name event
-Returns the unique name of the D-Bus object @var{event} is coming from.
+This function returns the unique name of the D-Bus object @var{event}
+is coming from.
 @end defun
 
 @defun dbus-event-path-name event
-Returns the object path of the D-Bus object @var{event} is coming from.
+This function returns the object path of the D-Bus object @var{event}
+is coming from.
 @end defun
 
 @defun dbus-event-interface-name event
-Returns the interface name of the D-Bus object @var{event} is coming from.
+This function returns the interface name of the D-Bus object
+@var{event} is coming from.
 @end defun
 
 @defun dbus-event-member-name event
-Returns the member name of the D-Bus object @var{event} is coming
-from.  It is either a signal name or a method name.
+This function returns the member name of the D-Bus object @var{event}
+is coming from.  It is either a signal name or a method name.
 @end defun
 
 D-Bus errors are not propagated during event handling, because it is
@@ -2009,7 +2002,7 @@ Errors and Events
 two arguments, the event and the error variable caught in
 @code{condition-case} by @code{dbus-error}.
 
-Such functions can be used the adapt the error signal to be raised.
+Such functions can be used to adapt the error signal to be raised.
 Example:
 
 @lisp
@@ -2019,12 +2012,12 @@ Errors and Events
     (message "my-dbus-event-error-handler: %S %S" event error)
     (signal 'file-error (cdr error))))
 
-(add-hook 'dbus-event-error-functions 'my-dbus-event-error-handler)
+(add-hook 'dbus-event-error-functions #'my-dbus-event-error-handler)
 @end lisp
 @end defvar
 
-Hook functions shall take into account, that there might be other
-D-Bus applications running.  Therefore, they shall check carefully,
+Hook functions should take into account that there might be other
+D-Bus applications running.  They should therefore check carefully,
 whether a given D-Bus error is related to them.

diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 4538399c75..06bd9e567f 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -182,7 +182,7 @@ dbus-event-error-functions
 ;;; Basic D-Bus message functions.
 
 (defvar dbus-return-values-table (make-hash-table :test 'equal)
-  "Hash table for temporary storing arguments of reply messages.
+  "Hash table for temporarily storing arguments of reply messages.
 A key in this hash table is a list (:serial BUS SERIAL), like in
 `dbus-registered-objects-table'.  BUS is either a Lisp symbol,
 `:system' or `:session', or a string denoting the bus address.
@@ -225,10 +225,10 @@ dbus-call-method
 object path SERVICE is registered at.  INTERFACE is an interface
 offered by SERVICE.  It must provide METHOD.
 
-If the parameter `:timeout' is given, the following integer TIMEOUT
-specifies the maximum number of milliseconds the method call must
-return.  The default value is 25,000.  If the method call doesn't
-return in time, a D-Bus error is raised.
+If the parameter `:timeout' is given, the following integer
+TIMEOUT specifies the maximum number of milliseconds before the
+method call must return.  The default value is 25,000.  If the
+method call doesn't return in time, a D-Bus error is raised.
 
 All other arguments ARGS are passed to METHOD as arguments.  They are
 converted into D-Bus types via the following rules:
@@ -248,14 +248,14 @@ dbus-call-method
 input arguments.  It follows the mapping rules:
 
   DBUS_TYPE_BOOLEAN     => t or nil
-  DBUS_TYPE_BYTE        => number
-  DBUS_TYPE_UINT16      => number
+  DBUS_TYPE_BYTE        => natural number
+  DBUS_TYPE_UINT16      => natural number
   DBUS_TYPE_INT16       => integer
-  DBUS_TYPE_UINT32      => number or float
-  DBUS_TYPE_UNIX_FD     => number or float
-  DBUS_TYPE_INT32       => integer or float
-  DBUS_TYPE_UINT64      => number or float
-  DBUS_TYPE_INT64       => integer or float
+  DBUS_TYPE_UINT32      => natural number
+  DBUS_TYPE_UNIX_FD     => natural number
+  DBUS_TYPE_INT32       => integer
+  DBUS_TYPE_UINT64      => natural number
+  DBUS_TYPE_INT64       => integer
   DBUS_TYPE_DOUBLE      => float
   DBUS_TYPE_STRING      => string
   DBUS_TYPE_OBJECT_PATH => string
@@ -268,9 +268,9 @@ dbus-call-method
 Example:
 
 \(dbus-call-method
-  :session \"org.gnome.seahorse\" \"/org/gnome/seahorse/keys/openpgp\"
-  \"org.gnome.seahorse.Keys\" \"GetKeyField\"
-  \"openpgp:657984B8C7A966DD\" \"simple-name\")
+ :session \"org.gnome.seahorse\" \"/org/gnome/seahorse/keys/openpgp\"
+ \"org.gnome.seahorse.Keys\" \"GetKeyField\"
+ \"openpgp:657984B8C7A966DD\" \"simple-name\")
 
   => (t (\"Philip R. Zimmermann\"))
 
@@ -278,9 +278,9 @@ dbus-call-method
 object is returned instead of a list containing this single Lisp object.
 
 \(dbus-call-method
-  :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
-  \"org.freedesktop.Hal.Device\" \"GetPropertyString\"
-  \"system.kernel.machine\")
+ :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
+ \"org.freedesktop.Hal.Device\" \"GetPropertyString\"
+ \"system.kernel.machine\")
 
   => \"i686\""
 
@@ -357,10 +357,10 @@ dbus-call-method-asynchronously
 return message has arrived.  If HANDLER is nil, no return message
 will be expected.
 
-If the parameter `:timeout' is given, the following integer TIMEOUT
-specifies the maximum number of milliseconds the method call must
-return.  The default value is 25,000.  If the method call doesn't
-return in time, a D-Bus error is raised.
+If the parameter `:timeout' is given, the following integer
+TIMEOUT specifies the maximum number of milliseconds before the
+method call must return.  The default value is 25,000.  If the
+method call doesn't return in time, a D-Bus error is raised.
 
 All other arguments ARGS are passed to METHOD as arguments.  They are
 converted into D-Bus types via the following rules:
@@ -377,19 +377,19 @@ dbus-call-method-asynchronously
 
 If HANDLER is a Lisp function, the function returns a key into the
 hash table `dbus-registered-objects-table'.  The corresponding entry
-in the hash table is removed, when the return message has been arrived,
+in the hash table is removed, when the return message arrives,
 and HANDLER is called.
 
 Example:
 
 \(dbus-call-method-asynchronously
-  :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
-  \"org.freedesktop.Hal.Device\" \"GetPropertyString\" \\='message
-  \"system.kernel.machine\")
+ :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/devices/computer\"
+ \"org.freedesktop.Hal.Device\" \"GetPropertyString\" \\='message
+ \"system.kernel.machine\")
 
-  => (:serial :system 2)
+  -| i686
 
-  -| i686"
+  => (:serial :system 2)"
 
   (or (featurep 'dbusbind)
       (signal 'dbus-error (list "Emacs not compiled with dbus support")))
@@ -438,8 +438,8 @@ dbus-send-signal
 Example:
 
 \(dbus-send-signal
-  :session nil \"/org/gnu/Emacs\" \"org.gnu.Emacs.FileManager\"
-  \"FileModified\" \"/home/albinus/.emacs\")"
+ :session nil \"/org/gnu/Emacs\" \"org.gnu.Emacs.FileManager\"
+ \"FileModified\" \"/home/albinus/.emacs\")"
 
   (or (featurep 'dbusbind)
       (signal 'dbus-error (list "Emacs not compiled with dbus support")))
@@ -625,17 +625,17 @@ dbus-register-signal
 It can be either a known name or the unique name of the D-Bus object
 sending the signal.
 
-PATH is the D-Bus object path SERVICE is registered.  INTERFACE
-is an interface offered by SERVICE.  It must provide SIGNAL.
-HANDLER is a Lisp function to be called when the signal is
-received.  It must accept as arguments the values SIGNAL is
+PATH is the D-Bus object path SERVICE is registered at.
+INTERFACE is an interface offered by SERVICE.  It must provide
+SIGNAL.  HANDLER is a Lisp function to be called when the signal
+is received.  It must accept as arguments the values SIGNAL is
 sending.
 
 SERVICE, PATH, INTERFACE and SIGNAL can be nil.  This is
 interpreted as a wildcard for the respective argument.
 
 The remaining arguments ARGS can be keywords or keyword string pairs.
-The meaning is as follows:
+Their meaning is as follows:
 
 `:argN' STRING:
 `:pathN' STRING: This stands for the Nth argument of the
@@ -643,8 +643,9 @@ dbus-register-signal
 matches as specified by D-Bus, while an `:argN' argument
 requires an exact match.
 
-`:arg-namespace' STRING: Register for the signals, which first
-argument defines the service or interface namespace STRING.
+`:arg-namespace' STRING: Register for those signals, whose first
+argument names a service or interface within the namespace
+STRING.
 
 `:path-namespace' STRING: Register for the object path namespace
 STRING.  All signals sent from an object path, which has STRING as
@@ -660,8 +661,8 @@ dbus-register-signal
   (message \"Device %s added\" device))
 
 \(dbus-register-signal
-  :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\"
-  \"org.freedesktop.Hal.Manager\" \"DeviceAdded\" \\='my-signal-handler)
+ :system \"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\"
+ \"org.freedesktop.Hal.Manager\" \"DeviceAdded\" \\='my-signal-handler)
 
   => ((:signal :system \"org.freedesktop.Hal.Manager\" \"DeviceAdded\")
       (\"org.freedesktop.Hal\" \"/org/freedesktop/Hal/Manager\" my-signal-handler))
@@ -773,24 +774,24 @@ dbus-register-signal
 
 (defun dbus-register-method
   (bus service path interface method handler &optional dont-register-service)
-  "Register for method METHOD on the D-Bus BUS.
+  "Register METHOD on the D-Bus BUS.
 
 BUS is either a Lisp symbol, `:system' or `:session', or a string
 denoting the bus address.
 
 SERVICE is the D-Bus service name of the D-Bus object METHOD is
-registered for.  It must be a known name (See discussion of
+registered for.  It must be a known name (see discussion of
 DONT-REGISTER-SERVICE below).
 
-PATH is the D-Bus object path SERVICE is registered (See discussion of
-DONT-REGISTER-SERVICE below).  INTERFACE is the interface offered by
-SERVICE.  It must provide METHOD.
+PATH is the D-Bus object path SERVICE is registered at (see
+discussion of DONT-REGISTER-SERVICE below).  INTERFACE is the
+interface offered by SERVICE.  It must provide METHOD.
 
 HANDLER is a Lisp function to be called when a method call is
 received.  It must accept the input arguments of METHOD.  The return
 value of HANDLER is used for composing the returning D-Bus message.
-In case HANDLER shall return a reply message with an empty argument
-list, HANDLER must return the symbol `:ignore'.
+If HANDLER returns a reply message with an empty argument list,
+HANDLER must return the symbol `:ignore'.
 
 When DONT-REGISTER-SERVICE is non-nil, the known name SERVICE is not
 registered.  This means that other D-Bus clients have no way of
@@ -888,8 +889,8 @@ dbus-unregister-object
 ;;; D-Bus type conversion.
 
 (defun dbus-string-to-byte-array (string)
-  "Transform STRING to list (:array :byte c1 :byte c2 ...).
-STRING shall be UTF8 coded."
+  "Transform STRING to list (:array :byte C1 :byte C2 ...).
+STRING shall be UTF-8 coded."
   (if (zerop (length string))
       '(:array :signature "y")
     (let (result)
@@ -897,7 +898,7 @@ dbus-string-to-byte-array
 	(setq result (append result (list :byte elt)))))))
 
 (defun dbus-byte-array-to-string (byte-array &optional multibyte)
-  "Transform BYTE-ARRAY into UTF8 coded string.
+  "Transform BYTE-ARRAY into UTF-8 coded string.
 BYTE-ARRAY must be a list of structure (c1 c2 ...), or a byte
 array as produced by `dbus-string-to-byte-array'.  The resulting
 string is unibyte encoded, unless MULTIBYTE is non-nil."
@@ -920,9 +921,9 @@ dbus-escape-as-identifier
 
    \"0123abc_xyz\\x01\\xff\" -> \"_30123abc_5fxyz_01_ff\"
 
-i.e. similar to URI encoding, but with \"_\" taking the role of \"%\",
-and a smaller allowed set. As a special case, \"\" is escaped to
-\"_\".
+i.e. similar to URI encoding, but with \"_\" taking the role of
+\"%\", and a smaller allowed set.  As a special case, \"\" is
+escaped to \"_\".
 
 Returns the escaped string.  Algorithm taken from
 telepathy-glib's `tp_escape_as_identifier'."
@@ -963,8 +964,8 @@ dbus-check-event
 are the arguments passed to HANDLER, when it is called during
 event handling in `dbus-handle-event'.
 
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
   (when dbus-debug (message "DBus-Event %s" event))
   (unless (and (listp event)
 	       (eq (car event) 'dbus-event)
@@ -1038,16 +1039,16 @@ dbus-event-bus-name
   "Return the bus name the event is coming from.
 The result is either a Lisp symbol, `:system' or `:session', or a
 string denoting the bus address.  EVENT is a D-Bus event, see
-`dbus-check-event'.  This function raises a `dbus-error' signal
-in case the event is not well formed."
+`dbus-check-event'.  This function signals a `dbus-error' if the
+event is not well formed."
   (dbus-check-event event)
   (nth 1 event))
 
 (defun dbus-event-message-type (event)
   "Return the message type of the corresponding D-Bus message.
 The result is a number.  EVENT is a D-Bus event, see
-`dbus-check-event'.  This function raises a `dbus-error' signal
-in case the event is not well formed."
+`dbus-check-event'.  This function signals a `dbus-error' if the
+event is not well formed."
   (dbus-check-event event)
   (nth 2 event))
 
@@ -1055,41 +1056,40 @@ dbus-event-serial-number
   "Return the serial number of the corresponding D-Bus message.
 The result is a number.  The serial number is needed for
 generating a reply message.  EVENT is a D-Bus event, see
-`dbus-check-event'.  This function raises a `dbus-error' signal
-in case the event is not well formed."
+`dbus-check-event'.  This function signals a `dbus-error' if the
+event is not well formed."
   (dbus-check-event event)
   (nth 3 event))
 
 (defun dbus-event-service-name (event)
   "Return the name of the D-Bus object the event is coming from.
 The result is a string.  EVENT is a D-Bus event, see `dbus-check-event'.
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
   (dbus-check-event event)
   (nth 4 event))
 
 (defun dbus-event-path-name (event)
   "Return the object path of the D-Bus object the event is coming from.
 The result is a string.  EVENT is a D-Bus event, see `dbus-check-event'.
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
   (dbus-check-event event)
   (nth 5 event))
 
 (defun dbus-event-interface-name (event)
   "Return the interface name of the D-Bus object the event is coming from.
 The result is a string.  EVENT is a D-Bus event, see `dbus-check-event'.
-This function raises a `dbus-error' signal in case the event is
-not well formed."
+This function signals a `dbus-error' if the event is not well
+formed."
   (dbus-check-event event)
   (nth 6 event))
 
 (defun dbus-event-member-name (event)
   "Return the member name the event is coming from.
-It is either a signal name or a method name. The result is a
+It is either a signal name or a method name.  The result is a
 string.  EVENT is a D-Bus event, see `dbus-check-event'.  This
-function raises a `dbus-error' signal in case the event is not
-well formed."
+function signals a `dbus-error' if the event is not well formed."
   (dbus-check-event event)
   (nth 7 event))
 
@@ -1097,10 +1097,10 @@ dbus-event-member-name
 ;;; D-Bus registered names.
 
 (defun dbus-list-activatable-names (&optional bus)
-  "Return the D-Bus service names which can be activated as list.
-If BUS is left nil, `:system' is assumed.  The result is a list
-of strings, which is nil when there are no activatable service
-names at all."
+  "Return a list of the D-Bus service names which can be activated.
+BUS defaults to `:system' when nil or omitted.  The result is a
+list of strings, which is nil when there are no activatable
+service names at all."
   (dbus-ignore-errors
     (dbus-call-method
      (or bus :system) dbus-service-dbus
@@ -1126,8 +1126,8 @@ dbus-list-known-names
 
 (defun dbus-list-queued-owners (bus service)
   "Return the unique names registered at D-Bus BUS and queued for SERVICE.
-The result is a list of strings, or nil when there are no
-queued name owners service names at all."
+The result is a list of strings, or nil when there are no queued
+name owner service names at all."
   (dbus-ignore-errors
     (dbus-call-method
      bus dbus-service-dbus dbus-path-dbus
@@ -1144,13 +1144,13 @@ dbus-get-name-owner
 (defun dbus-ping (bus service &optional timeout)
   "Check whether SERVICE is registered for D-Bus BUS.
 TIMEOUT, a nonnegative integer, specifies the maximum number of
-milliseconds `dbus-ping' must return.  The default value is 25,000.
+milliseconds before `dbus-ping' must return.  The default value
+is 25,000.
 
-Note, that this autoloads SERVICE if it is not running yet.  If
-it shall be checked whether SERVICE is already running, one shall
-apply
+Note, that this autoloads SERVICE if it is not running yet.  To
+check whether SERVICE is already running, you can instead write
 
-  (member service \(dbus-list-known-names bus))"
+  (member service (dbus-list-known-names bus))"
   ;; "Ping" raises a D-Bus error if SERVICE does not exist.
   ;; Otherwise, it returns silently with nil.
   (condition-case nil
@@ -1239,11 +1239,11 @@ dbus-introspect-get-interface-names
   "Return all interface names of SERVICE in D-Bus BUS at object path PATH.
 It returns a list of strings.
 
-There will be always the default interface
-\"org.freedesktop.DBus.Introspectable\".  Another default
-interface is \"org.freedesktop.DBus.Properties\".  If present,
-\"interface\" objects can also have \"property\" objects as
-children, beside \"method\" and \"signal\" objects."
+The default interface \"org.freedesktop.DBus.Introspectable\" is
+always present.  Another default interface is
+\"org.freedesktop.DBus.Properties\".  If present, \"interface\"
+objects can also have \"property\" objects as children, beside
+\"method\" and \"signal\" objects."
   (let ((object (dbus-introspect-xml bus service path))
 	result)
     (dolist (elt (xml-get-children object 'interface) (nreverse result))
@@ -1251,9 +1251,10 @@ dbus-introspect-get-interface-names
 
 (defun dbus-introspect-get-interface (bus service path interface)
   "Return the INTERFACE of SERVICE in D-Bus BUS at object path PATH.
-The return value is an XML object.  INTERFACE must be a string,
-element of the list returned by `dbus-introspect-get-interface-names'.
-The resulting \"interface\" object can contain \"method\", \"signal\",
+The return value is an XML object.  INTERFACE must be a string
+and a member of the list returned by
+`dbus-introspect-get-interface-names'.  The resulting
+\"interface\" object can contain \"method\", \"signal\",
 \"property\" and \"annotation\" children."
   (let ((elt (xml-get-children
 	      (dbus-introspect-xml bus service path) 'interface)))
@@ -1273,9 +1274,9 @@ dbus-introspect-get-method-names
       (push (dbus-introspect-get-attribute elt "name") result))))
 
 (defun dbus-introspect-get-method (bus service path interface method)
-  "Return method METHOD of interface INTERFACE as XML object.
+  "Return method METHOD of interface INTERFACE as an XML object.
 It must be located at SERVICE in D-Bus BUS at object path PATH.
-METHOD must be a string, element of the list returned by
+METHOD must be a string and a member of the list returned by
 `dbus-introspect-get-method-names'.  The resulting \"method\"
 object can contain \"arg\" and \"annotation\" children."
   (let ((elt (xml-get-children
@@ -1296,7 +1297,7 @@ dbus-introspect-get-signal-names
       (push (dbus-introspect-get-attribute elt "name") result))))
 
 (defun dbus-introspect-get-signal (bus service path interface signal)
-  "Return signal SIGNAL of interface INTERFACE as XML object.
+  "Return signal SIGNAL of interface INTERFACE as an XML object.
 It must be located at SERVICE in D-Bus BUS at object path PATH.
 SIGNAL must be a string, element of the list returned by
 `dbus-introspect-get-signal-names'.  The resulting \"signal\"
@@ -1319,9 +1320,9 @@ dbus-introspect-get-property-names
       (push (dbus-introspect-get-attribute elt "name") result))))
 
 (defun dbus-introspect-get-property (bus service path interface property)
-  "Return PROPERTY of INTERFACE as XML object.
+  "Return PROPERTY of INTERFACE as an XML object.
 It must be located at SERVICE in D-Bus BUS at object path PATH.
-PROPERTY must be a string, element of the list returned by
+PROPERTY must be a string and a member of the list returned by
 `dbus-introspect-get-property-names'.  The resulting PROPERTY
 object can contain \"annotation\" children."
   (let ((elt (xml-get-children
@@ -1336,7 +1337,7 @@ dbus-introspect-get-property
 
 (defun dbus-introspect-get-annotation-names
   (bus service path interface &optional name)
-  "Return all annotation names as list of strings.
+  "Return all annotation names as a list of strings.
 If NAME is nil, the annotations are children of INTERFACE,
 otherwise NAME must be a \"method\", \"signal\", or \"property\"
 object, where the annotations belong to."
@@ -1352,7 +1353,7 @@ dbus-introspect-get-annotation-names
 
 (defun dbus-introspect-get-annotation
   (bus service path interface name annotation)
-  "Return ANNOTATION as XML object.
+  "Return ANNOTATION as an XML object.
 If NAME is nil, ANNOTATION is a child of INTERFACE, otherwise
 NAME must be the name of a \"method\", \"signal\", or
 \"property\" object, where the ANNOTATION belongs to."
@@ -1374,7 +1375,7 @@ dbus-introspect-get-annotation
     (car elt)))
 
 (defun dbus-introspect-get-argument-names (bus service path interface name)
-  "Return a list of all argument names as list of strings.
+  "Return a list of all argument names as a list of strings.
 NAME must be a \"method\" or \"signal\" object.
 
 Argument names are optional, the function can return nil
@@ -1388,8 +1389,9 @@ dbus-introspect-get-argument-names
 
 (defun dbus-introspect-get-argument (bus service path interface name arg)
   "Return argument ARG as XML object.
-NAME must be a \"method\" or \"signal\" object.  ARG must be a string,
-element of the list returned by `dbus-introspect-get-argument-names'."
+NAME must be a \"method\" or \"signal\" object.  ARG must be a
+string and a member of the list returned by
+`dbus-introspect-get-argument-names'."
   (let ((elt (xml-get-children
 	      (or (dbus-introspect-get-method bus service path interface name)
 		  (dbus-introspect-get-signal bus service path interface name))
@@ -1402,7 +1404,7 @@ dbus-introspect-get-argument
 
 (defun dbus-introspect-get-signature
   (bus service path interface name &optional direction)
-  "Return signature of a `method' or `signal', represented by NAME, as string.
+  "Return signature of a `method' or `signal' represented by NAME as a string.
 If NAME is a `method', DIRECTION can be either \"in\" or \"out\".
 If DIRECTION is nil, \"in\" is assumed.
 
@@ -1450,9 +1452,8 @@ dbus-get-property
 
 (defun dbus-set-property (bus service path interface property value)
   "Set value of PROPERTY of INTERFACE to VALUE.
-It will be checked at BUS, SERVICE, PATH.  When the value has
-been set successful, the result is VALUE.  Otherwise, nil is
-returned."
+It will be checked at BUS, SERVICE, PATH.  When the value is
+successfully set return VALUE.  Otherwise, return nil."
   (dbus-ignore-errors
    ;; "Set" requires a variant.
    (dbus-call-method
@@ -1479,15 +1480,15 @@ dbus-get-all-properties
 (defun dbus-register-property
   (bus service path interface property access value
    &optional emits-signal dont-register-service)
-  "Register property PROPERTY on the D-Bus BUS.
+  "Register PROPERTY on the D-Bus BUS.
 
 BUS is either a Lisp symbol, `:system' or `:session', or a string
 denoting the bus address.
 
 SERVICE is the D-Bus service name of the D-Bus.  It must be a
-known name (See discussion of DONT-REGISTER-SERVICE below).
+known name (see discussion of DONT-REGISTER-SERVICE below).
 
-PATH is the D-Bus object path SERVICE is registered (See
+PATH is the D-Bus object path SERVICE is registered at (see
 discussion of DONT-REGISTER-SERVICE below).  INTERFACE is the
 name of the interface used at PATH, PROPERTY is the name of the
 property of INTERFACE.  ACCESS indicates, whether the property
@@ -1625,8 +1626,8 @@ dbus-get-all-managed-objects
   "Return all objects at BUS, SERVICE, PATH, and the children of PATH.
 The result is a list of objects.  Every object is a cons of an
 existing path name, and the list of available interface objects.
-An interface object is another cons, which car is the interface
-name, and the cdr is the list of properties as returned by
+An interface object is another cons, whose car is the interface
+name and cdr is the list of properties as returned by
 `dbus-get-all-properties' for that path and interface.  Example:
 
 \(dbus-get-all-managed-objects :session \"org.gnome.SettingsDaemon\" \"/\")
@@ -1782,12 +1783,13 @@ dbus-init-bus
 the system and session buses, this function is called when loading
 `dbus.el', there is no need to call it again.
 
-The function returns a number, which counts the connections this Emacs
-session has established to the BUS under the same unique name (see
-`dbus-get-unique-name').  It depends on the libraries Emacs is linked
-with, and on the environment Emacs is running.  For example, if Emacs
-is linked with the gtk toolkit, and it runs in a GTK-aware environment
-like Gnome, another connection might already be established.
+The function returns the number of connections this Emacs session
+has established to the BUS under the same unique name (see
+`dbus-get-unique-name').  It depends on the libraries Emacs is
+linked with, and on the environment Emacs is running.  For
+example, if Emacs is linked with the GTK+ toolkit, and it runs in
+a GTK+-aware environment like GNOME, another connection might
+already be established.
 
 When PRIVATE is non-nil, a new connection is established instead of
 reusing an existing one.  It results in a new unique name at the bus.
-- 
2.26.2

And these implementation cleanups for master:

>From dad68bc11e6b0a64a733029804f88e0f18a5401c Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <[email-masked]>
Date: Sat, 6 Jun 2020 13:20:06 +0100
Subject: [PATCH] Various dbus.el cleanups

* lisp/net/dbus.el: Remove unneeded dependency on cl-lib.el.  Quote
function symbols as such.
(dbus-ignore-errors): Don't add macro name to font-lock keywords, as
emacs-lisp-mode now dynamically fontifies new macro definitions.
(dbus-call-method-non-blocking): Define as obosolete alias using
define-obsolete-function-alias.
(dbus-register-signal, dbus-escape-as-identifier): Simplify.  Use
regexp \` and \' in place of ^ and $.
(dbus--parse-xml-buffer): New function for libxml2 compatibility.
(dbus-introspect-xml): Use it.

(dbus-string-to-byte-array, dbus-byte-array-to-string)
(dbus-unescape-from-identifier, dbus-list-known-names)
(dbus-introspect-get-all-nodes, dbus-get-all-properties)
(dbus-get-all-managed-objects): Simplify.

(dbus--introspect-names, dbus--introspect-name): New convenience
functions.
(dbus-introspect-get-node-names)
(dbus-introspect-get-interface-names)
(dbus-introspect-get-interface, dbus-introspect-get-method-names)
(dbus-introspect-get-method, dbus-introspect-get-signal-names)
(dbus-introspect-get-signal, dbus-introspect-get-property-names)
(dbus-introspect-get-property)
(dbus-introspect-get-annotation-names)
(dbus-introspect-get-annotation)
(dbus-introspect-get-argument-names, dbus-introspect-get-argument):
Use them to DRY.

* test/lisp/net/dbus-tests.el (dbus-test-all): Quote function
symbols as such.
---
 lisp/net/dbus.el            | 269 +++++++++++++++---------------------
 test/lisp/net/dbus-tests.el |   4 +-
 2 files changed, 111 insertions(+), 162 deletions(-)

diff --git a/lisp/net/dbus.el b/lisp/net/dbus.el
index 4538399c75..c882d1ae7a 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -51,9 +51,6 @@ dbus-registered-objects-table
 (unless (boundp 'dbus-debug)
   (defvar dbus-debug nil))
 
-;; Pacify byte compiler.
-(eval-when-compile (require 'cl-lib))
-
 (require 'xml)
 
 (defconst dbus-service-dbus "org.freedesktop.DBus"
@@ -169,7 +166,6 @@ dbus-ignore-errors
   `(condition-case err
        (progn ,@body)
      (dbus-error (when dbus-debug (signal (car err) (cdr err))))))
-(font-lock-add-keywords 'emacs-lisp-mode '("\\<dbus-ignore-errors\\>"))
 
 (define-obsolete-variable-alias 'dbus-event-error-hooks
   'dbus-event-error-functions "24.3")
@@ -181,7 +177,7 @@ dbus-event-error-functions
 
 ;;; Basic D-Bus message functions.
 
-(defvar dbus-return-values-table (make-hash-table :test 'equal)
+(defvar dbus-return-values-table (make-hash-table :test #'equal)
   "Hash table for temporary storing arguments of reply messages.
 A key in this hash table is a list (:serial BUS SERIAL), like in
 `dbus-registered-objects-table'.  BUS is either a Lisp symbol,
@@ -301,8 +297,8 @@ dbus-call-method
         (check-interval 0.001)
 	(key
 	 (apply
-	  'dbus-message-internal dbus-message-type-method-call
-	  bus service path interface method 'dbus-call-method-handler args))
+          #'dbus-message-internal dbus-message-type-method-call
+          bus service path interface method #'dbus-call-method-handler args))
         (result (cons :pending nil)))
 
     ;; Wait until `dbus-call-method-handler' has put the result into
@@ -339,8 +335,8 @@ dbus-call-method
       (remhash key dbus-return-values-table))))
 
 ;; `dbus-call-method' works non-blocking now.
-(defalias 'dbus-call-method-non-blocking 'dbus-call-method)
-(make-obsolete 'dbus-call-method-non-blocking 'dbus-call-method "24.3")
+(define-obsolete-function-alias 'dbus-call-method-non-blocking
+  #'dbus-call-method "24.3")
 
 (defun dbus-call-method-asynchronously
  (bus service path interface method handler &rest args)
@@ -406,7 +402,7 @@ dbus-call-method-asynchronously
   (or (null handler) (functionp handler)
       (signal 'wrong-type-argument (list 'functionp handler)))
 
-  (apply 'dbus-message-internal dbus-message-type-method-call
+  (apply #'dbus-message-internal dbus-message-type-method-call
 	 bus service path interface method handler args))
 
 (defun dbus-send-signal (bus service path interface signal &rest args)
@@ -454,7 +450,7 @@ dbus-send-signal
   (or (stringp signal)
       (signal 'wrong-type-argument (list 'stringp signal)))
 
-  (apply 'dbus-message-internal dbus-message-type-signal
+  (apply #'dbus-message-internal dbus-message-type-signal
 	 bus service path interface signal args))
 
 (defun dbus-method-return-internal (bus service serial &rest args)
@@ -470,7 +466,7 @@ dbus-method-return-internal
   (or (natnump serial)
       (signal 'wrong-type-argument (list 'natnump serial)))
 
-  (apply 'dbus-message-internal dbus-message-type-method-return
+  (apply #'dbus-message-internal dbus-message-type-method-return
 	 bus service serial args))
 
 (defun dbus-method-error-internal (bus service serial &rest args)
@@ -486,7 +482,7 @@ dbus-method-error-internal
   (or (natnump serial)
       (signal 'wrong-type-argument (list 'natnump serial)))
 
-  (apply 'dbus-message-internal dbus-message-type-error
+  (apply #'dbus-message-internal dbus-message-type-error
 	 bus service serial args))
 
 
@@ -552,13 +548,13 @@ dbus-register-service
 `:already-owner': Service is already the primary owner."
 
   ;; Add Peer handler.
-  (dbus-register-method
-   bus service nil dbus-interface-peer "Ping" 'dbus-peer-handler 'dont-register)
+  (dbus-register-method bus service nil dbus-interface-peer "Ping"
+                        #'dbus-peer-handler 'dont-register)
 
   ;; Add ObjectManager handler.
   (dbus-register-method
    bus service nil dbus-interface-objectmanager "GetManagedObjects"
-   'dbus-managed-objects-handler 'dont-register)
+   #'dbus-managed-objects-handler 'dont-register)
 
   (let ((arg 0)
 	reply)
@@ -680,7 +676,7 @@ dbus-register-signal
     (if (and (stringp service)
 	     (not (zerop (length service)))
 	     (not (string-equal service dbus-service-dbus))
-	     (not (string-match "^:" service)))
+             (/= (string-to-char service) ?:))
 	(setq uname (dbus-get-name-owner bus service))
       (setq uname service))
 
@@ -709,7 +705,7 @@ dbus-register-signal
 		;; `:arg0' .. `:arg63', `:path0' .. `:path63'.
 		((and (keywordp key)
 		      (string-match
-		       "^:\\(arg\\|path\\)\\([[:digit:]]+\\)$"
+                       "\\`:\\(arg\\|path\\)\\([[:digit:]]+\\)\\'"
 		       (symbol-name key)))
 		 (setq counter (match-string 2 (symbol-name key))
 		       args (cdr args)
@@ -725,9 +721,7 @@ dbus-register-signal
 		      "path" "")
 		  value))
 		;; `:arg-namespace', `:path-namespace'.
-		((and (keywordp key)
-		      (string-match
-		       "^:\\(arg\\|path\\)-namespace$" (symbol-name key)))
+                ((memq key '(:arg-namespace :path-namespace))
 		 (setq args (cdr args)
 		       value (car args))
 		 (unless (stringp value)
@@ -735,8 +729,7 @@ dbus-register-signal
 			   (list "Wrong argument" key value)))
 		 (format
 		  ",%s='%s'"
-		  (if (string-equal (match-string 1 (symbol-name key)) "path")
-		      "path_namespace" "arg0namespace")
+                  (if (eq key :path-namespace) "path_namespace" "arg0namespace")
 		  value))
 		;; `:eavesdrop'.
 		((eq key :eavesdrop)
@@ -750,11 +743,11 @@ dbus-register-signal
 	 bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
 	 "AddMatch" rule)
       (dbus-error
-       (if (not (string-match "eavesdrop" rule))
+       (if (not (string-match-p "eavesdrop" rule))
 	   (signal (car err) (cdr err))
 	 ;; The D-Bus spec says we shall fall back to a rule without eavesdrop.
 	 (when dbus-debug (message "Removing eavesdrop from rule %s" rule))
-	 (setq rule (replace-regexp-in-string ",eavesdrop='true'" "" rule))
+         (setq rule (replace-regexp-in-string ",eavesdrop='true'" "" rule t t))
 	 (dbus-call-method
 	  bus dbus-service-dbus dbus-path-dbus dbus-interface-dbus
 	  "AddMatch" rule))))
@@ -892,9 +885,7 @@ dbus-string-to-byte-array
 STRING shall be UTF8 coded."
   (if (zerop (length string))
       '(:array :signature "y")
-    (let (result)
-      (dolist (elt (string-to-list string) (append '(:array) result))
-	(setq result (append result (list :byte elt)))))))
+    (cons :array (mapcan (lambda (c) (list :byte c)) string))))
 
 (defun dbus-byte-array-to-string (byte-array &optional multibyte)
   "Transform BYTE-ARRAY into UTF8 coded string.
@@ -902,12 +893,9 @@ dbus-byte-array-to-string
 array as produced by `dbus-string-to-byte-array'.  The resulting
 string is unibyte encoded, unless MULTIBYTE is non-nil."
   (apply
-   (if multibyte 'string 'unibyte-string)
-   (if (equal byte-array '(:array :signature "y"))
-       nil
-     (let (result)
-       (dolist (elt byte-array result)
-	 (when (characterp elt) (setq result (append result `(,elt)))))))))
+   (if multibyte #'string #'unibyte-string)
+   (unless (equal byte-array '(:array :signature "y"))
+     (seq-filter #'characterp byte-array))))
 
 (defun dbus-escape-as-identifier (string)
   "Escape an arbitrary STRING so it follows the rules for a C identifier.
@@ -929,9 +917,9 @@ dbus-escape-as-identifier
   (if (zerop (length string))
       "_"
     (replace-regexp-in-string
-     "^[0-9]\\|[^A-Za-z0-9]"
+     "\\`[0-9]\\|[^A-Za-z0-9]"
      (lambda (x) (format "_%2x" (aref x 0)))
-     string)))
+     string nil t)))
 
 (defun dbus-unescape-from-identifier (string)
   "Retrieve the original string from the encoded STRING as unibyte string.
@@ -941,7 +929,7 @@ dbus-unescape-from-identifier
     (replace-regexp-in-string
      "_.."
      (lambda (x) (byte-to-string (string-to-number (substring x 1) 16)))
-     string)))
+     string nil t)))
 
 
 ;;; D-Bus events.
@@ -1019,7 +1007,7 @@ dbus-handle-event
 	    (if (eq result :ignore)
 		(dbus-method-return-internal
 		 (nth 1 event) (nth 4 event) (nth 3 event))
-	      (apply 'dbus-method-return-internal
+              (apply #'dbus-method-return-internal
 		     (nth 1 event) (nth 4 event) (nth 3 event)
 		     (if (consp result) result (list result)))))))
     ;; Error handling.
@@ -1119,10 +1107,9 @@ dbus-list-names
 (defun dbus-list-known-names (bus)
   "Retrieve all services which correspond to a known name in BUS.
 A service has a known name if it doesn't start with \":\"."
-  (let (result)
-    (dolist (name (dbus-list-names bus) (nreverse result))
-      (unless (string-equal ":" (substring name 0 1))
-	(push name result)))))
+  (seq-remove (lambda (name)
+                (= (string-to-char name) ?:))
+              (dbus-list-names bus)))
 
 (defun dbus-list-queued-owners (bus service)
   "Return the unique names registered at D-Bus BUS and queued for SERVICE.
@@ -1182,6 +1169,18 @@ dbus-peer-handler
 
 ;;; D-Bus introspection.
 
+(defsubst dbus--introspect-names (object tag)
+  "Return the names of the children of OBJECT with TAG."
+  (mapcar (lambda (elt)
+            (dbus-introspect-get-attribute elt "name"))
+          (xml-get-children object tag)))
+
+(defsubst dbus--introspect-name (object tag name)
+  "Return the first child of OBJECT with TAG, whose name is NAME."
+  (seq-find (lambda (elt)
+              (string-equal (dbus-introspect-get-attribute elt "name") name))
+            (xml-get-children object tag)))
+
 (defun dbus-introspect (bus service path)
   "Return all interfaces and sub-nodes of SERVICE,
 registered at object path PATH at bus BUS.
@@ -1197,17 +1196,25 @@ dbus-introspect
      bus service path dbus-interface-introspectable "Introspect"
      :timeout 1000)))
 
+(defalias 'dbus--parse-xml-buffer
+  (if (libxml-available-p)
+      (lambda ()
+        (xml-remove-comments (point-min) (point-max))
+        (libxml-parse-xml-region (point-min) (point-max)))
+    (lambda ()
+      (car (xml-parse-region (point-min) (point-max)))))
+  "Compatibility shim for `libxml-parse-xml-region'.")
+
 (defun dbus-introspect-xml (bus service path)
   "Return the introspection data of SERVICE in D-Bus BUS at object path PATH.
 The data are a parsed list.  The root object is a \"node\",
 representing the object path PATH.  The root object can contain
 \"interface\" and further \"node\" objects."
-  ;; We don't want to raise errors.
-  (xml-node-name
-   (ignore-errors
-     (with-temp-buffer
-       (insert (dbus-introspect bus service path))
-       (xml-parse-region (point-min) (point-max))))))
+  (with-temp-buffer
+    ;; We don't want to raise errors.
+    (ignore-errors
+      (insert (dbus-introspect bus service path))
+      (dbus--parse-xml-buffer))))
 
 (defun dbus-introspect-get-attribute (object attribute)
   "Return the ATTRIBUTE value of D-Bus introspection OBJECT.
@@ -1219,21 +1226,15 @@ dbus-introspect-get-node-names
   "Return all node names of SERVICE in D-Bus BUS at object path PATH.
 It returns a list of strings.  The node names stand for further
 object paths of the D-Bus service."
-  (let ((object (dbus-introspect-xml bus service path))
-	result)
-    (dolist (elt (xml-get-children object 'node) (nreverse result))
-      (push (dbus-introspect-get-attribute elt "name") result))))
+  (dbus--introspect-names (dbus-introspect-xml bus service path) 'node))
 
 (defun dbus-introspect-get-all-nodes (bus service path)
   "Return all node names of SERVICE in D-Bus BUS at object path PATH.
 It returns a list of strings, which are further object paths of SERVICE."
-  (let ((result (list path)))
-    (dolist (elt
-             (dbus-introspect-get-node-names bus service path)
-             result)
-      (setq elt (expand-file-name elt path))
-      (setq result
-            (append result (dbus-introspect-get-all-nodes bus service elt))))))
+  (cons path (mapcan (lambda (elt)
+                       (setq elt (expand-file-name elt path))
+                       (dbus-introspect-get-all-nodes bus service elt))
+                     (dbus-introspect-get-node-names bus service path))))
 
 (defun dbus-introspect-get-interface-names (bus service path)
   "Return all interface names of SERVICE in D-Bus BUS at object path PATH.
@@ -1244,10 +1245,7 @@ dbus-introspect-get-interface-names
 interface is \"org.freedesktop.DBus.Properties\".  If present,
 \"interface\" objects can also have \"property\" objects as
 children, beside \"method\" and \"signal\" objects."
-  (let ((object (dbus-introspect-xml bus service path))
-	result)
-    (dolist (elt (xml-get-children object 'interface) (nreverse result))
-      (push (dbus-introspect-get-attribute elt "name") result))))
+  (dbus--introspect-names (dbus-introspect-xml bus service path) 'interface))
 
 (defun dbus-introspect-get-interface (bus service path interface)
   "Return the INTERFACE of SERVICE in D-Bus BUS at object path PATH.
@@ -1255,22 +1253,14 @@ dbus-introspect-get-interface
 element of the list returned by `dbus-introspect-get-interface-names'.
 The resulting \"interface\" object can contain \"method\", \"signal\",
 \"property\" and \"annotation\" children."
-  (let ((elt (xml-get-children
-	      (dbus-introspect-xml bus service path) 'interface)))
-    (while (and elt
-		(not (string-equal
-		      interface
-		      (dbus-introspect-get-attribute (car elt) "name"))))
-      (setq elt (cdr elt)))
-    (car elt)))
+  (dbus--introspect-name (dbus-introspect-xml bus service path)
+                         'interface interface))
 
 (defun dbus-introspect-get-method-names (bus service path interface)
   "Return a list of strings of all method names of INTERFACE.
 SERVICE is a service of D-Bus BUS at object path PATH."
-  (let ((object (dbus-introspect-get-interface bus service path interface))
-	result)
-    (dolist (elt (xml-get-children object 'method) (nreverse result))
-      (push (dbus-introspect-get-attribute elt "name") result))))
+  (dbus--introspect-names
+   (dbus-introspect-get-interface bus service path interface) 'method))
 
 (defun dbus-introspect-get-method (bus service path interface method)
   "Return method METHOD of interface INTERFACE as XML object.
@@ -1278,22 +1268,15 @@ dbus-introspect-get-method
 METHOD must be a string, element of the list returned by
 `dbus-introspect-get-method-names'.  The resulting \"method\"
 object can contain \"arg\" and \"annotation\" children."
-  (let ((elt (xml-get-children
-	      (dbus-introspect-get-interface bus service path interface)
-	      'method)))
-    (while (and elt
-		(not (string-equal
-		      method (dbus-introspect-get-attribute (car elt) "name"))))
-      (setq elt (cdr elt)))
-    (car elt)))
+  (dbus--introspect-name
+   (dbus-introspect-get-interface bus service path interface)
+   'method method))
 
 (defun dbus-introspect-get-signal-names (bus service path interface)
   "Return a list of strings of all signal names of INTERFACE.
 SERVICE is a service of D-Bus BUS at object path PATH."
-  (let ((object (dbus-introspect-get-interface bus service path interface))
-	result)
-    (dolist (elt (xml-get-children object 'signal) (nreverse result))
-      (push (dbus-introspect-get-attribute elt "name") result))))
+  (dbus--introspect-names
+   (dbus-introspect-get-interface bus service path interface) 'signal))
 
 (defun dbus-introspect-get-signal (bus service path interface signal)
   "Return signal SIGNAL of interface INTERFACE as XML object.
@@ -1301,22 +1284,15 @@ dbus-introspect-get-signal
 SIGNAL must be a string, element of the list returned by
 `dbus-introspect-get-signal-names'.  The resulting \"signal\"
 object can contain \"arg\" and \"annotation\" children."
-  (let ((elt (xml-get-children
-	      (dbus-introspect-get-interface bus service path interface)
-	      'signal)))
-    (while (and elt
-		(not (string-equal
-		      signal (dbus-introspect-get-attribute (car elt) "name"))))
-      (setq elt (cdr elt)))
-    (car elt)))
+  (dbus--introspect-name
+   (dbus-introspect-get-interface bus service path interface)
+   'signal signal))
 
 (defun dbus-introspect-get-property-names (bus service path interface)
   "Return a list of strings of all property names of INTERFACE.
 SERVICE is a service of D-Bus BUS at object path PATH."
-  (let ((object (dbus-introspect-get-interface bus service path interface))
-	result)
-    (dolist (elt (xml-get-children object 'property) (nreverse result))
-      (push (dbus-introspect-get-attribute elt "name") result))))
+  (dbus--introspect-names
+   (dbus-introspect-get-interface bus service path interface) 'property))
 
 (defun dbus-introspect-get-property (bus service path interface property)
   "Return PROPERTY of INTERFACE as XML object.
@@ -1324,15 +1300,9 @@ dbus-introspect-get-property
 PROPERTY must be a string, element of the list returned by
 `dbus-introspect-get-property-names'.  The resulting PROPERTY
 object can contain \"annotation\" children."
-  (let ((elt (xml-get-children
-	      (dbus-introspect-get-interface bus service path interface)
-	      'property)))
-    (while (and elt
-		(not (string-equal
-		      property
-		      (dbus-introspect-get-attribute (car elt) "name"))))
-      (setq elt (cdr elt)))
-    (car elt)))
+  (dbus--introspect-name
+   (dbus-introspect-get-interface bus service path interface)
+   'property property))
 
 (defun dbus-introspect-get-annotation-names
   (bus service path interface &optional name)
@@ -1340,15 +1310,13 @@ dbus-introspect-get-annotation-names
 If NAME is nil, the annotations are children of INTERFACE,
 otherwise NAME must be a \"method\", \"signal\", or \"property\"
 object, where the annotations belong to."
-  (let ((object
-	 (if name
-	     (or (dbus-introspect-get-method bus service path interface name)
-		 (dbus-introspect-get-signal bus service path interface name)
-		 (dbus-introspect-get-property bus service path interface name))
-	   (dbus-introspect-get-interface bus service path interface)))
-	result)
-    (dolist (elt (xml-get-children object 'annotation) (nreverse result))
-      (push (dbus-introspect-get-attribute elt "name") result))))
+  (dbus--introspect-names
+   (if name
+       (or (dbus-introspect-get-method bus service path interface name)
+           (dbus-introspect-get-signal bus service path interface name)
+           (dbus-introspect-get-property bus service path interface name))
+     (dbus-introspect-get-interface bus service path interface))
+   'annotation))
 
 (defun dbus-introspect-get-annotation
   (bus service path interface name annotation)
@@ -1356,22 +1324,13 @@ dbus-introspect-get-annotation
 If NAME is nil, ANNOTATION is a child of INTERFACE, otherwise
 NAME must be the name of a \"method\", \"signal\", or
 \"property\" object, where the ANNOTATION belongs to."
-  (let ((elt (xml-get-children
-	      (if name
-		  (or (dbus-introspect-get-method
-		       bus service path interface name)
-		      (dbus-introspect-get-signal
-		       bus service path interface name)
-		      (dbus-introspect-get-property
-		       bus service path interface name))
-		(dbus-introspect-get-interface bus service path interface))
-	      'annotation)))
-    (while (and elt
-		(not (string-equal
-		      annotation
-		      (dbus-introspect-get-attribute (car elt) "name"))))
-      (setq elt (cdr elt)))
-    (car elt)))
+  (dbus--introspect-name
+   (if name
+       (or (dbus-introspect-get-method bus service path interface name)
+           (dbus-introspect-get-signal bus service path interface name)
+           (dbus-introspect-get-property bus service path interface name))
+     (dbus-introspect-get-interface bus service path interface))
+   'annotation annotation))
 
 (defun dbus-introspect-get-argument-names (bus service path interface name)
   "Return a list of all argument names as list of strings.
@@ -1379,26 +1338,19 @@ dbus-introspect-get-argument-names
 
 Argument names are optional, the function can return nil
 therefore, even if the method or signal has arguments."
-  (let ((object
-	 (or (dbus-introspect-get-method bus service path interface name)
-	     (dbus-introspect-get-signal bus service path interface name)))
-	result)
-    (dolist (elt (xml-get-children object 'arg) (nreverse result))
-      (push (dbus-introspect-get-attribute elt "name") result))))
+  (dbus--introspect-names
+   (or (dbus-introspect-get-method bus service path interface name)
+       (dbus-introspect-get-signal bus service path interface name))
+   'arg))
 
 (defun dbus-introspect-get-argument (bus service path interface name arg)
   "Return argument ARG as XML object.
 NAME must be a \"method\" or \"signal\" object.  ARG must be a string,
 element of the list returned by `dbus-introspect-get-argument-names'."
-  (let ((elt (xml-get-children
-	      (or (dbus-introspect-get-method bus service path interface name)
-		  (dbus-introspect-get-signal bus service path interface name))
-	      'arg)))
-    (while (and elt
-		(not (string-equal
-		      arg (dbus-introspect-get-attribute (car elt) "name"))))
-      (setq elt (cdr elt)))
-    (car elt)))
+  (dbus--introspect-name
+   (or (dbus-introspect-get-method bus service path interface name)
+       (dbus-introspect-get-signal bus service path interface name))
+   'arg arg))
 
 (defun dbus-introspect-get-signature
   (bus service path interface name &optional direction)
@@ -1468,13 +1420,10 @@ dbus-get-all-properties
 nil is returned."
   (dbus-ignore-errors
     ;; "GetAll" returns "a{sv}".
-    (let (result)
-      (dolist (dict
-	       (dbus-call-method
-		bus service path dbus-interface-properties
-		"GetAll" :timeout 500 interface)
-	       (nreverse result))
-	(push (cons (car dict) (cl-caadr dict)) result)))))
+    (mapcar (lambda (dict)
+              (cons (car dict) (caadr dict)))
+            (dbus-call-method bus service path dbus-interface-properties
+                              "GetAll" :timeout 500 interface))))
 
 (defun dbus-register-property
   (bus service path interface property access value
@@ -1519,13 +1468,13 @@ dbus-register-property
   ;; Add handlers for the three property-related methods.
   (dbus-register-method
    bus service path dbus-interface-properties "Get"
-   'dbus-property-handler 'dont-register)
+   #'dbus-property-handler 'dont-register)
   (dbus-register-method
    bus service path dbus-interface-properties "GetAll"
-   'dbus-property-handler 'dont-register)
+   #'dbus-property-handler 'dont-register)
   (dbus-register-method
    bus service path dbus-interface-properties "Set"
-   'dbus-property-handler 'dont-register)
+   #'dbus-property-handler 'dont-register)
 
   ;; Register SERVICE.
   (unless (or dont-register-service (member service (dbus-list-names bus)))
@@ -1672,7 +1621,7 @@ dbus-get-all-managed-objects
 		(if (cadr entry2)
 		    ;; "sv".
 		    (dolist (entry3 (cadr entry2))
-		      (setcdr entry3 (cl-caadr entry3)))
+                      (setcdr entry3 (caadr entry3)))
 		  (setcdr entry2 nil)))))
 
 	;; Fallback: collect the information.  Slooow!
@@ -1729,7 +1678,7 @@ dbus-managed-objects-handler
 			   (append
 			    (butlast last-input-event 4)
 			    (list object dbus-interface-properties
-				  "GetAll" 'dbus-property-handler))))
+                                  "GetAll" #'dbus-property-handler))))
 		      (dbus-property-handler interface))))
 		   (cdr (assoc object result)))))))))
        dbus-registered-objects-table)
diff --git a/test/lisp/net/dbus-tests.el b/test/lisp/net/dbus-tests.el
index e263c4563f..45c9851365 100644
--- a/test/lisp/net/dbus-tests.el
+++ b/test/lisp/net/dbus-tests.el
@@ -176,8 +176,8 @@ dbus-test03-peer-interface
 (defun dbus-test-all (&optional interactive)
   "Run all tests for \\[dbus]."
   (interactive "p")
-  (funcall
-   (if interactive 'ert-run-tests-interactively 'ert-run-tests-batch) "^dbus"))
+  (funcall (if interactive #'ert-run-tests-interactively #'ert-run-tests-batch)
+           "^dbus"))
 
 (provide 'dbus-tests)
 ;;; dbus-tests.el ends here
-- 
2.26.2

Are these changes acceptable?  WDYT?

Thanks,

-- 
Basil

In GNU Emacs 27.0.91 (build 12, x86_64-pc-linux-gnu, X toolkit, Xaw3d scroll bars)
 of 2020-06-06 built on thunk
Repository revision: c1f4c0bc839324d2049ae45a74381684a5727f60
Repository branch: blc/27/dbus
Windowing system distributor 'The X.Org Foundation', version 11.0.12008000
System Description: Debian GNU/Linux bullseye/sid

Configured using:
 'configure 'CC=ccache gcc' 'CFLAGS=-O0 -g3 -ggdb -gdwarf-4'
 --config-cache --prefix=/home/blc/.local --program-suffix=27
 --enable-checking=yes,glyphs --enable-check-lisp-object-type
 --with-x-toolkit=lucid --with-file-notification=yes --with-x'

Configured features:
XAW3D XPM JPEG TIFF GIF PNG RSVG SOUND GPM DBUS GSETTINGS GLIB NOTIFY
INOTIFY ACL LIBSELINUX GNUTLS LIBXML2 FREETYPE HARFBUZZ M17N_FLT LIBOTF
XFT ZLIB TOOLKIT_SCROLL_BARS LUCID X11 XDBE XIM MODULES THREADS
LIBSYSTEMD JSON PDUMPER LCMS2 GMP