[elpa] externals/bluetooth 8f3dcaa 11/33: move some of the comments into docstrings

[Stefan Monnier]

branch: externals/bluetooth
commit 8f3dcaab73dee361b1f64c2424c062b78415bb24
Author: Raffael Stocker <r.stocker@mnet-mail.de>
Commit: Raffael Stocker <r.stocker@mnet-mail.de>

    move some of the comments into docstrings
---
 bluetooth.el | 40 +++++++++++++++++++++++-----------------
 1 file changed, 23 insertions(+), 17 deletions(-)

diff --git a/bluetooth.el b/bluetooth.el
index 33e5ed4..9816371 100644
--- a/bluetooth.el
+++ b/bluetooth.el
@@ -78,17 +78,22 @@ This is usually `:system' if bluetoothd runs as a system 
service, or
 
 (put 'bluetooth--mode-info 'risky-local-variable t)
 
-;; The state information list defines the kind of adapter state displayed
-;; in the mode-line.  The first element of a sublist is an adapter property,
-;; the second is a list containing first the current status of the item 
(t/nil),
-;; second the displayed string if the property is non-nil and
-;; third the displayed string if the property is nil.  If a
-;; display element is nil, nothing will be displayed for this property.
+
 (defvar bluetooth--mode-state '(("Powered" . (nil nil "off"))
                                ("Discoverable" . (nil "discoverable" nil))
                                ("Pairable" . (nil "pairable" nil))
                                ("Discovering" . (nil "scan" nil)))
-  "Mode line adapter state information.")
+  "Mode line adapter state information.
+
+The state information list defines the kind of adapter state
+displayed in the mode-line.  The first element of each sub-list
+is an adapter property, the second is a list containing the
+ - current status of the item (t or nil),
+ - string displayed if the property is non-nil,
+ - string displayed if the property is nil.
+
+If a display element is nil, nothing will be displayed for this
+property and state.")
 
 ;; Bluez service name as defined by the Bluez API
 (defconst bluetooth--service "org.bluez" "D-Bus service name of Bluez.")
@@ -219,12 +224,13 @@ The generated function name has the form 
`bluetoothPREFIX-NAME'."
          ((null value) "no")
          (t "yes"))))
 
-;; List format for the main display buffer.
-;; NOTE: the strings MUST correspond to Bluez device properties
-;; as they are used to gather the information from Bluez.
 (defconst bluetooth--list-format
   [("Alias" 24 t) ("Paired" 8 t) ("Connected" 11 t) ("Address" 17 t)
-   ("Blocked" 9 t) ("Trusted" 9 t)] "The list view format for bluetooth mode.")
+   ("Blocked" 9 t) ("Trusted" 9 t)]
+  "The list view format for bluetooth mode.
+
+NOTE: the strings MUST correspond to Bluez device properties
+as they are used to gather the information from Bluez.")
 
 ;; This function provides the list entries for the tabulated-list
 ;; view.  It is called from `tabulated-list-print'.
@@ -400,11 +406,10 @@ This function only uses the first adapter reported by 
Bluez."
     (unless (string-blank-p info)
       (concat " [" info "]"))))
 
-;; This D-Bus signal handler listens to property changes of the
-;; adapter and updates the status display accordingly.
 (defun bluetooth--handle-prop-change (interface data &rest _)
   "Handle property change signals on D-Bus INTERFACE as given by DATA.
-Only adapter properties are considered."
+Only adapter properties are considered.  If an adapter property changes,
+update the status display accordingly."
   (when (string= interface (alist-get :adapter bluetooth--interfaces))
     (dolist (elt data)
       (let ((prop (car elt))
@@ -412,10 +417,11 @@ Only adapter properties are considered."
        (when-let (state (cdr (assoc prop bluetooth--mode-state)))
          (setcar state value))))))
 
-;; This function registers a signal handler for the _first_ adapter
-;; reported by Bluez.
 (defun bluetooth--register-signal-handler ()
-  "Register signal handler for adapter property changes."
+  "Register a signal handler for adapter property changes.
+
+This function registers a signal handler only for the first
+adapter reported by Bluez."
   (let ((adapters (dbus-introspect-get-node-names bluetooth-bluez-bus
                                                  bluetooth--service
                                                  bluetooth--root)))