Clean up D-Bus documentation (bug#41744)

* 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.

3 files changed, 531 insertions, 528 deletions

diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi
index dc6877c9eca..cd8694be8a3 100644
--- a/doc/lispref/errors.texi
+++ b/doc/lispref/errors.texi
@@ -79,9 +79,8 @@ The message is @samp{Symbol's chain of variable indirections contains
 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 9e5f1ccc6fd..167d2bd5ac1 100644
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -167,7 +167,7 @@ default) or the symbol @code{:session}.  An activatable service is
 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 @@ activatable service names at all.  Example:
 @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 @@ strings like @samp{org.freedesktop.DBus}.  Names starting with
 @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 @@ known names at all.
 
 @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 @@ string.
 
 @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 @@ string.
 @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 @@ without autostarting it, one shall apply
 @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 @@ format.  Example:
 
 @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,46 +423,51 @@ the HAL specification}.}
 @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"))
-       (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")))
-       )
-       @dots{}
-       (signal ((name . "HitsAdded"))
-         (arg ((name . "search") (type . "s")))
-         (arg ((name . "count") (type . "u")))
-       )
-     )
-     @dots{}
-   )
+    (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"))))
+      @dots{}
+      (signal ((name . "HitsAdded"))
+        (arg ((name . "search") (type . "s")))
+        (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 +484,12 @@ The first elements, to be introspected for a D-Bus object, are further
 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 +520,10 @@ Example:
 @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 +531,8 @@ children.  Example:
 
 @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 +542,27 @@ children.  Example:
 @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 +571,8 @@ With these functions, it is possible to retrieve all introspection
 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 +581,7 @@ data from a running system:
       (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 +594,15 @@ Methods and signals are the communication means to D-Bus.  The
 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 +611,36 @@ Return a list of strings of all method names of @var{interface} of
 @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 +648,21 @@ Return a list of strings of all signal names of @var{interface} of
 @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 +673,8 @@ returned by @code{dbus-introspect-get-signal-names}.  Example:
 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 +687,14 @@ Often, they are used to instruct generators, how to generate code from
 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 +704,26 @@ also the @samp{org.freedesktop.DBus.Properties} interface.
 @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 +737,23 @@ result can be any valid D-Bus value, or @code{nil} if there is no
 
 @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 +767,8 @@ If there are no properties, @code{nil} is returned.  Example:
 
 @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 +783,13 @@ This function returns all objects at @var{bus}, @var{service},
 @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 +819,28 @@ An overview of all existing object paths, their interfaces and
 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 +862,30 @@ If set, don't expect a reply to the @code{method} call; defaults to @code{nil}
 @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 +899,41 @@ Methods and signals have arguments.  They are described in the
 @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 +944,16 @@ non-@code{nil}, @var{direction} must be @samp{out}.  Example:
 
 @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 +1008,27 @@ types are represented by the type symbols @code{:byte},
 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 +1043,13 @@ D-Bus compound type rules.
 @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 +1059,27 @@ elements of this array.  Example:
 
 @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 +1090,10 @@ UTF8 string, this function performs the conversion.  Example:
 @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 +1114,18 @@ Output parameters of D-Bus methods and signals are mapped to Lisp
 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 +1137,21 @@ objects.
 @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 +1163,9 @@ to the corresponding string.  The string is unibyte encoded, unless
 @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 +1179,9 @@ that string:
 
 @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 +1198,13 @@ that string:
 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 +1213,14 @@ D-Bus object path, @var{service} is registered at.  @var{interface} is
 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 +1228,9 @@ Lisp objects, according to the type conversion rules described in
 
 @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 +1241,10 @@ object.  Example:
 
 @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 +1260,17 @@ emulate the @code{lshal} command on GNU/Linux systems:
 
 @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 +1307,35 @@ D-Bus object path, @var{service} is registered at.  @var{interface} is
 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 +1351,8 @@ clients.  Names on the D-Bus can be registered and unregistered using
 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 +1362,33 @@ must be a known name.
 
 @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 +1399,27 @@ D-Bus.
 
 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 +1441,10 @@ With this function, an application registers @var{method} on the D-Bus
 @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 +1461,8 @@ If @var{handler} wants to return just one Lisp object and it is not a
 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 +1473,7 @@ clients from discovering the still incomplete interface.
 
 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 +1482,14 @@ registration for @var{method}.  Example:
 
 @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 +1497,9 @@ registration for @var{method}.  Example:
 @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 +1523,9 @@ You can indicate an error by raising the Emacs signal
       (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 +1549,7 @@ With this function, an application declares a @var{property} on the D-Bus
 @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 +1558,7 @@ discussion of @var{dont-register-service} below).
 @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 +1583,15 @@ clients from discovering the still incomplete interface.
 
 @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 +1622,28 @@ possible via the command line tool @code{dbus-send} in a shell:
       ]
 @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 +1671,22 @@ doesn't matter whether another object has registered for @var{signal}.
 
 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 +1701,11 @@ With this function, an application registers for a signal on the D-Bus
 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 +1720,31 @@ The remaining arguments @var{args} can be keywords or keyword string
 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:
-
-@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.
-
-@item @code{:arg-namespace} @var{string}:@*
-Register for the signals, which first argument defines the service or
-interface namespace @var{string}.
-
-@item @code{:path-namespace} @var{string}:@*
+@code{nil} argument might be used to preserve the order.}  Their
+meaning is as follows:
+
+@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 :arg-namespace @var{string}
+Register for those signals, whose first argument names a service or
+interface within the 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 +1754,10 @@ registration for @var{signal}.  Example:
 (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 +1767,8 @@ registration for @var{signal}.  Example:
 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 +1779,7 @@ for a dummy signal, and check the result:
 @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 +1794,14 @@ for a dummy signal, and check the result:
 
 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 +1809,12 @@ corresponding bus.  For the system and session buses, this function
 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 +1829,9 @@ Example: You initialize a connection to the AT-SPI bus on your host:
 
 @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 +1846,7 @@ Example: You initialize a connection to the AT-SPI bus on your host:
 
 @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 +1857,14 @@ Example: You initialize a connection to the AT-SPI bus on your host:
 @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 +1875,7 @@ function adds to or modifies that environment when activating services.
 
 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 +1914,7 @@ Input parameters of @code{dbus-call-method},
 @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 +1965,39 @@ There exist convenience functions which could be called inside a
 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 +2011,7 @@ D-Bus error happens in the event handler.  Every function must accept
 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 +2021,12 @@ Example:
     (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 4538399c751..06bd9e567fe 100644
--- a/lisp/net/dbus.el
+++ b/lisp/net/dbus.el
@@ -182,7 +182,7 @@ caught in `condition-case' by `dbus-error'.")
 ;;; 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 @@ SERVICE is the D-Bus service name to be used.  PATH is the D-Bus
 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 @@ Lisp objects.  The type conversion happens the other direction as for
 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 @@ input arguments.  It follows the mapping rules:
 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 @@ If the result of the METHOD call is just one value, the converted Lisp
 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 @@ HANDLER is a Lisp function, which is called when the corresponding
 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 @@ type symbols, see Info node `(dbus)Type Conversion'.
 
 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 @@ type symbols, see Info node `(dbus)Type Conversion'.
 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 @@ SERVICE is the D-Bus service name used by the sending D-Bus object.
 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 @@ signal.  `:pathN' arguments can be used for object path wildcard
 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 @@ Example:
   (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 @@ Example:
 
 (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 @@ association to the service from D-Bus."
 ;;; 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 @@ STRING shall be UTF8 coded."
         (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 @@ lower-case hex digits:
 
    \"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 @@ the function which has been registered for this message.  ARGS
 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 @@ If the HANDLER returns a `dbus-error', it is propagated as return message."
   "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 @@ in case the event is not well formed."
   "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 @@ well formed."
 ;;; 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 @@ A service has a known name if it doesn't start with \":\"."
 
 (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 @@ The result is either a string, or nil if there is no 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 @@ It returns a list of strings, which are further object paths of SERVICE."
   "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 @@ children, beside \"method\" and \"signal\" objects."
 
 (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 @@ SERVICE is a service of D-Bus BUS at object path PATH."
       (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 @@ SERVICE is a service of D-Bus BUS at object path PATH."
       (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 @@ SERVICE is a service of D-Bus BUS at object path PATH."
       (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 @@ object can contain \"annotation\" children."
 
 (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 @@ object, where the annotations belong to."
 
 (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 @@ NAME must be the name of a \"method\", \"signal\", or
     (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 @@ therefore, even if the method or signal has arguments."
 
 (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 @@ element of the list returned by `dbus-introspect-get-argument-names'."
 
 (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 @@ valid D-Bus value, or nil if there is no 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 @@ nil is returned."
 (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 @@ It will be registered for all objects created by `dbus-register-property'."
   "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 @@ can be a string denoting the address of the corresponding bus.  For
 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.