satisfy checkdoc

* exwm-background.el (exwm-background--connected-p): Add docstring.
(exwm-background--connect): Add docstring.
* exwm-core.el (exwm-debug-log-time-function):
(exwm-debug): Rename to exwm-debug-mode; define obsolete alias for old name.
(exwm--debug): Update docstring to reflect above name change.
(exwm--log): condition on exwm-debug-mode
(exwm-mode-map): update exwm-debug-mode binding
* exwm-floating.el (exwm-floating--set-allowed-actions):
Rename TILLING parameter to TILED-P; update docstring.
(exwm-floating--start-moveresize): Add parameters to docstring.
(exwm-floating--do-moveresize): Add parameter to docstring.
* exwm-input.el (exwm-input-prefix-keys): Remove embedded keybinding from docstring.
(exwm-input--on-PropertyNotify): Add parameter to docstring.
(exwm-input--on-EnterNotify): Add parameter to docstring.
(exwm-input--on-keysyms-update): Add docstring.
(exwm-input--set-active-window): Add parameter to docstring.
(exwm-input--on-ButtonPress): Add parameter to docstring.
(exwm-input--on-KeyPress): Add parameter to docstring.
(exwm-input--on-CreateNotify): Add parameter to docstring.
(exwm-input--grab-global-prefix-keys): Add docstring.
(exwm-input--set-key): Add docstring.
(exwm-input-set-key): Add parameter to docstring.
(exwm-input--unread-event): Add docstring.
(exwm-input--translate): Add docstring.
(exwm-input--cache-event): Add parameter to docstring.
(exwm-input--on-KeyPress-line-mode): Rename parameter; add parameter to docstring.
(exwm-input--on-KeyPress-char-mode): Rename parameter; add parameter to docstring.
(exwm-input-grab-keyboard): Add parameter to docstring.
(exwm-input-release-keyboard): Add parameter to docstring.
(exwm-input-toggle-keyboard): Add parameter to docstring.
(exwm-input-send-next-key): Rename parameter; mention limit in docstring.
(exwm-input--set-simulation-keys): Rename parameter; add parameter to docstring.
(exwm-input--read-keys): Add docstring.
(exwm-input-set-simulation-key): Add parameters to docstring.
(exwm-input-send-simulation-key): Rename parameter; add parameter to docstring.
* exwm-randr.el (exwm-randr--on-ScreenChangeNotify): Add parameter to docstring.
(exwm-randr--on-Notify): Add parameter to docstring.
(exwm-randr--on-ConfigureNotify): Add parameter to docstring.
* exwm-xim.el (exwm-xim--on-ClientMessage): Add parameter to docstring.
* exwm.el (exwm-restart): Remove question mark from prompt arg
(exwm-enable): Remove question mark from prompt arg; add parameter to docstring.
(exwm--confirm-kill-terminal): Remove question mark from prompt arg.
(exwm--confirm-kill-emacs): Ensure prompt ends in question mark.

exwm-background.el

@@ -156,10 +156,12 @@ may kill this connection when they replace it.")
   (xcb:flush exwm-background--connection))
 
 (defun exwm-background--connected-p ()
+  "Return t if a live background connection process exists and is connected."
   (and exwm-background--connection
        (process-live-p (slot-value exwm-background--connection 'process))))
 
 (defun exwm-background--connect ()
+  "Establish background Pixmap connection."
   (unless (exwm-background--connected-p)
     (setq exwm-background--connection (xcb:connect))
     ;;prevent query message on exit

exwm-core.el

@@ -38,12 +38,12 @@
   :group 'exwm)
 
 (defcustom exwm-debug-log-time-function #'exwm-debug-log-uptime
-  "Function used for generating timestamps in `exwm-debug' logs.
+  "Function used for generating timestamps in debug log.
 
 Here are some predefined candidates:
 `exwm-debug-log-uptime': Display the uptime of this Emacs instance.
 `exwm-debug-log-time': Display time of day.
-`nil': Disable timestamp."
+nil: Disable timestamp."
   :type `(choice (const :tag "Emacs uptime" ,#'exwm-debug-log-uptime)
                  (const :tag "Time of day" ,#'exwm-debug-log-time)
                  (const :tag "Off" nil)
@@ -98,14 +98,15 @@ Here are some predefined candidates:
 (declare-function exwm-workspace-switch "exwm-workspace.el"
                   (frame-or-index &optional force))
 
-(define-minor-mode exwm-debug
+(define-minor-mode exwm-debug-mode
   "Debug-logging enabled if non-nil."
   :global t
   :group 'exwm-debug)
+(define-obsolete-function-alias 'exwm-debug 'exwm-debug-mode "0.30")
 
 (defmacro exwm--debug (&rest forms)
-  "Evaluate FORMS if mode `exwm-debug' is active."
+  "Evaluate FORMS if `exwm-debug-mode' is active."
-  (when exwm-debug `(progn ,@forms)))
+  (when exwm-debug-mode `(progn ,@forms)))
 
 (defmacro exwm--log (&optional format-string &rest objects)
   "Emit a message prepending the name of the function being executed.
@@ -113,7 +114,7 @@ Here are some predefined candidates:
 FORMAT-STRING is a string specifying the message to output, as in
 `format'.  The OBJECTS arguments specify the substitutions."
   (unless format-string (setq format-string ""))
-  `(when exwm-debug
+  `(when exwm-debug-mode
      (xcb-debug:message ,(concat "%s%s:\t" format-string "\n")
                         (if exwm-debug-log-time-function
                             (funcall exwm-debug-log-time-function)
@@ -285,7 +286,7 @@ One of `line-mode' or `char-mode'.")
   (let ((map (make-sparse-keymap)))
     (define-key map "\C-c\C-d\C-l" #'xcb-debug:clear)
     (define-key map "\C-c\C-d\C-m" #'xcb-debug:mark)
-    (define-key map "\C-c\C-d\C-t" #'exwm-debug)
+    (define-key map "\C-c\C-d\C-t" #'exwm-debug-mode)
     (define-key map "\C-c\C-f" #'exwm-layout-set-fullscreen)
     (define-key map "\C-c\C-h" #'exwm-floating-hide)
     (define-key map "\C-c\C-k" #'exwm-input-release-keyboard)

exwm-floating.el

@@ -125,13 +125,14 @@ This hook runs in the context of the corresponding buffer."
 (declare-function exwm-workspace--update-offsets "exwm-workspace.el" ())
 (declare-function exwm-workspace--workarea "exwm-workspace.el" (frame))
 
-(defun exwm-floating--set-allowed-actions (id tilling)
+(defun exwm-floating--set-allowed-actions (id tiled-p)
-  "Set _NET_WM_ALLOWED_ACTIONS."
+  "Set _NET_WM_ALLOWED_ACTIONS for window with ID.
+If TILED-P is non-nil, set actions for tiled window."
   (exwm--log "#x%x" id)
   (xcb:+request exwm--connection
       (make-instance 'xcb:ewmh:set-_NET_WM_ALLOWED_ACTIONS
                      :window id
-                     :data (if tilling
+                     :data (if tiled-p
                                (vector xcb:Atom:_NET_WM_ACTION_MINIMIZE
                                        xcb:Atom:_NET_WM_ACTION_FULLSCREEN
                                        xcb:Atom:_NET_WM_ACTION_CHANGE_DESKTOP
@@ -466,7 +467,9 @@ This hook runs in the context of the corresponding buffer."
     (select-frame-set-input-focus exwm-workspace--current)))
 
 (defun exwm-floating--start-moveresize (id &optional type)
-  "Start move/resize."
+  "Start move/resize for window with ID.
+When non-nil, TYPE indicates the type of move/resize.
+Float resizing is stopped when TYPE is nil."
   (exwm--log "#x%x" id)
   (let ((buffer-or-id (or (exwm--id->buffer id) id))
         frame container-or-id x y width height cursor)
@@ -672,7 +675,7 @@ This hook runs in the context of the corresponding buffer."
     (setq exwm-floating--moveresize-calculate nil)))
 
 (defun exwm-floating--do-moveresize (data _synthetic)
-  "Perform move/resize."
+  "Perform move/resize on floating window with DATA."
   (when exwm-floating--moveresize-calculate
     (let* ((obj (make-instance 'xcb:MotionNotify))
            result value-mask x y width height buffer-or-id container-or-id)

exwm-input.el

@@ -46,7 +46,6 @@
   '(?\C-x ?\C-u ?\C-h ?\M-x ?\M-` ?\M-& ?\M-:)
   "List of prefix keys EXWM should forward to Emacs when in `line-mode'.
 
-The point is to make keys like `C-x C-f' forwarded to Emacs in `line-mode'.
 There is no need to add prefix keys for global/simulation keys or those
 defined in `exwm-mode-map' here."
   :type '(repeat key-sequence)
@@ -231,7 +230,7 @@ ARGS are additional arguments to CALLBACK."
   (xcb:flush exwm--connection))
 
 (defun exwm-input--on-PropertyNotify (data _synthetic)
-  "Handle PropertyNotify events."
+  "Handle PropertyNotify events with DATA."
   (exwm--log)
   (when exwm-input--timestamp-callback
     (let ((obj (make-instance 'xcb:PropertyNotify)))
@@ -246,7 +245,7 @@ ARGS are additional arguments to CALLBACK."
 (defvar exwm-input--last-enter-notify-position nil)
 
 (defun exwm-input--on-EnterNotify (data _synthetic)
-  "Handle EnterNotify events."
+  "Handle EnterNotify events with DATA."
   (let ((evt (make-instance 'xcb:EnterNotify))
         buffer window frame frame-xid edges fake-evt)
     (xcb:unmarshal evt data)
@@ -292,6 +291,7 @@ ARGS are additional arguments to CALLBACK."
       (setq exwm-input--last-enter-notify-position (vector root-x root-y)))))
 
 (defun exwm-input--on-keysyms-update ()
+  "Update global prefix keys."
   (exwm--log)
   (let ((exwm-input--global-prefix-keys nil))
     (exwm-input--update-global-prefix-keys)))
@@ -386,7 +386,8 @@ attempt later."
             (xcb:flush exwm--connection)))))))
 
 (defun exwm-input--set-active-window (&optional id)
-  "Set _NET_ACTIVE_WINDOW."
+  "Set _NET_ACTIVE_WINDOW.
+When non-nil, ID is passed as the window data."
   (exwm--log)
   (xcb:+request exwm--connection
       (make-instance 'xcb:ewmh:set-_NET_ACTIVE_WINDOW
@@ -394,7 +395,7 @@ attempt later."
                      :data (or id xcb:Window:None))))
 
 (defun exwm-input--on-ButtonPress (data _synthetic)
-  "Handle ButtonPress event."
+  "Handle ButtonPress event with DATA."
   (let ((obj (make-instance 'xcb:ButtonPress))
         (mode xcb:Allow:SyncPointer)
         button-event window buffer frame fake-last-command)
@@ -466,7 +467,7 @@ attempt later."
   (run-hooks 'exwm-input--event-hook))
 
 (defun exwm-input--on-KeyPress (data _synthetic)
-  "Handle KeyPress event."
+  "Handle KeyPress event with DATA."
   (with-current-buffer (window-buffer (selected-window))
     (let ((obj (make-instance 'xcb:KeyPress)))
       (xcb:unmarshal obj data)
@@ -482,7 +483,7 @@ attempt later."
     (run-hooks 'exwm-input--event-hook)))
 
 (defun exwm-input--on-CreateNotify (data _synthetic)
-  "Handle CreateNotify events."
+  "Handle CreateNotify events with DATA."
   (exwm--log)
   (let ((evt (make-instance 'xcb:CreateNotify)))
     (xcb:unmarshal evt data)
@@ -505,6 +506,7 @@ attempt later."
                            'children))))))
 
 (defun exwm-input--grab-global-prefix-keys (&rest xwins)
+  "Grab global prefix keys in XWINS."
   (exwm--log)
   (let ((req (make-instance 'xcb:GrabKey
                             :owner-events 0
@@ -539,6 +541,7 @@ attempt later."
     (xcb:flush exwm--connection)))
 
 (defun exwm-input--set-key (key command)
+  "Set KEY to COMMAND."
   (exwm--log "key: %s, command: %s" key command)
   (global-set-key key command)
   (cl-pushnew key exwm-input--global-keys))
@@ -566,9 +569,9 @@ Notes:
 
 ;;;###autoload
 (defun exwm-input-set-key (key command)
-  "Set a global key binding.
+  "Set a global KEY binding to COMMAND.
 
-The new key binding only takes effect in real time when this command is
+The new binding only takes effect in real time when this command is
 called interactively, and is lost when this session ends unless it's
 specifically saved in the Customize interface for `exwm-input-global-keys'.
 
@@ -583,6 +586,7 @@ instead."
     (exwm-input--update-global-prefix-keys)))
 
 (defsubst exwm-input--unread-event (event)
+  "Append EVENT to `unread-command-events'."
   (declare (indent defun))
   (setq unread-command-events
         (append unread-command-events `((t . ,event)))))
@@ -602,6 +606,7 @@ instead."
   event)
 
 (cl-defun exwm-input--translate (key)
+  "Translate KEY."
   (let (translation)
     (dolist (map (list input-decode-map
                        local-function-key-map
@@ -614,7 +619,8 @@ instead."
   key)
 
 (defun exwm-input--cache-event (event &optional temp-line-mode)
-  "Cache EVENT."
+  "Cache EVENT.
+When non-nil, TEMP-LINE-MODE temporarily puts the window in line mode."
   (exwm--log "%s" event)
   (setq exwm-input--line-mode-cache
         (vconcat exwm-input--line-mode-cache (vector event)))
@@ -681,9 +687,9 @@ Current buffer must be an `exwm-mode' buffer."
                 (error-message-string err))
      (xcb-debug:backtrace))))
 
-(defun exwm-input--on-KeyPress-line-mode (key-press raw-data)
+(defun exwm-input--on-KeyPress-line-mode (keypress raw-data)
-  "Parse X KeyPress event to Emacs key event and then feed the command loop."
+  "Feed parsed X KEYPRESS event with RAW-DATA to Emacs command loop."
-  (with-slots (detail state) key-press
+  (with-slots (detail state) keypress
     (let ((keysym (xcb:keysyms:keycode->keysym exwm--connection detail state))
           event raw-event mode)
       (exwm--log "%s" keysym)
@@ -707,7 +713,7 @@ Current buffer must be an `exwm-mode' buffer."
           (xcb:+request exwm--connection
               (make-instance 'xcb:SendEvent
                              :propagate 0
-                             :destination (slot-value key-press 'event)
+                             :destination (slot-value keypress 'event)
                              :event-mask xcb:EventMask:NoEvent
                              :event raw-data)))
         (when event
@@ -722,9 +728,9 @@ Current buffer must be an `exwm-mode' buffer."
                          :time xcb:Time:CurrentTime))
       (xcb:flush exwm--connection))))
 
-(defun exwm-input--on-KeyPress-char-mode (key-press &optional _raw-data)
+(defun exwm-input--on-KeyPress-char-mode (keypress &optional _raw-data)
-  "Handle KeyPress event in `char-mode'."
+  "Handle `char-mode' KEYPRESS event."
-  (with-slots (detail state) key-press
+  (with-slots (detail state) keypress
     (let ((keysym (xcb:keysyms:keycode->keysym exwm--connection detail state))
           event raw-event)
       (exwm--log "%s" keysym)
@@ -840,7 +846,8 @@ button event."
 
 ;;;###autoload
 (defun exwm-input-grab-keyboard (&optional id)
-  "Switch to `line-mode'."
+  "Switch to `line-mode`.
+When ID is non-nil, grab key events on its corresponding window."
   (interactive (list (when (derived-mode-p 'exwm-mode)
                        (exwm--buffer->id (window-buffer)))))
   (when id
@@ -851,7 +858,8 @@ button event."
 
 ;;;###autoload
 (defun exwm-input-release-keyboard (&optional id)
-  "Switch to `char-mode`."
+  "Switch to `char-mode`.
+When ID is non-nil, release keyboard events on its corresponding window."
   (interactive (list (when (derived-mode-p 'exwm-mode)
                        (exwm--buffer->id (window-buffer)))))
   (when id
@@ -862,7 +870,8 @@ button event."
 
 ;;;###autoload
 (defun exwm-input-toggle-keyboard (&optional id)
-  "Toggle between `line-mode' and `char-mode'."
+  "Toggle between `line-mode' and `char-mode'.
+When ID is non-nil, toggle in its correpsonding window."
   (interactive (list (when (derived-mode-p 'exwm-mode)
                        (exwm--buffer->id (window-buffer)))))
   (when id
@@ -904,25 +913,24 @@ button event."
     (xcb:flush exwm--connection)))
 
 ;;;###autoload
-(cl-defun exwm-input-send-next-key (times &optional end-key)
+(cl-defun exwm-input-send-next-key (n &optional end-key)
-  "Send next key to client window.
+  "Send next N keys to client window.
-
+N is currently capped at 12.
-EXWM will prompt for the key to send.  This command can be prefixed to send
+EXWM will prompt for the key to send.
-multiple keys.  If END-KEY is non-nil, stop sending keys if it's pressed."
+If END-KEY is non-nil, stop sending keys if it's pressed."
   (interactive "p")
   (exwm--log)
-  (unless (derived-mode-p 'exwm-mode)
+  (unless (derived-mode-p 'exwm-mode) (cl-return-from exwm-input-send-next-key))
-    (cl-return-from exwm-input-send-next-key))
+  (setq n (min n 12))
-  (when (> times 12) (setq times 12))
   (let (key keys)
-    (dotimes (i times)
+    (dotimes (i n)
       ;; Skip events not from keyboard
       (let ((exwm-input-line-mode-passthrough t))
         (catch 'break
           (while t
             (setq key (read-key (format "Send key: %s (%d/%d) %s"
                                         (key-description keys)
-                                        (1+ i) times
+                                        (1+ i) n
                                         (if end-key
                                             (concat "To exit, press: "
                                                     (key-description
@@ -933,10 +941,11 @@ multiple keys.  If END-KEY is non-nil, stop sending keys if it's pressed."
       (when (eq key end-key) (cl-return-from exwm-input-send-next-key))
       (exwm-input--fake-key key))))
 
-(defun exwm-input--set-simulation-keys (simulation-keys &optional no-refresh)
+(defun exwm-input--set-simulation-keys (keys &optional cache)
-  "Set simulation keys."
+  "Set simulation KEYS.
-  (exwm--log "%s" simulation-keys)
+If CACHE is non-nil reuse `exwm-input--simulation-keys' cache."
-  (unless no-refresh
+  (exwm--log "%s" keys)
+  (unless cache
     ;; Unbind simulation keys.
     (let ((hash (buffer-local-value 'exwm-input--simulation-keys
                                     (current-buffer))))
@@ -949,7 +958,7 @@ multiple keys.  If END-KEY is non-nil, stop sending keys if it's pressed."
                  hash)))
     ;; Abandon the old hash table.
     (setq exwm-input--simulation-keys (make-hash-table :test #'equal)))
-  (dolist (i simulation-keys)
+  (dolist (i keys)
     (let ((original (vconcat (car i)))
           (simulated (cdr i)))
       (setq simulated (if (sequencep simulated)
@@ -966,7 +975,7 @@ multiple keys.  If END-KEY is non-nil, stop sending keys if it's pressed."
                (if exwm-input--local-simulation-keys
                    (local-set-key key #'exwm-input-send-simulation-key)
                  (define-key exwm-mode-map key
-                   #'exwm-input-send-simulation-key))))
+                             #'exwm-input-send-simulation-key))))
            exwm-input--simulation-keys))
 
 (defcustom exwm-input-simulation-keys nil
@@ -1013,6 +1022,7 @@ Notes:
   :type '(repeat function))
 
 (cl-defun exwm-input--read-keys (prompt stop-key)
+  "Read keys with PROMPT until STOP-KEY pressed."
   (let ((cursor-in-echo-area t)
         keys key)
     (while (not (eq key stop-key))
@@ -1026,7 +1036,7 @@ Notes:
 
 ;;;###autoload
 (defun exwm-input-set-simulation-key (original-key simulated-key)
-  "Set a simulation key.
+  "Set ORIGINAL-KEY to  SIMULATED-KEY.
 
 The simulation key takes effect in real time, but is lost when this session
 ends unless it's specifically saved in the Customize interface for
@@ -1069,15 +1079,15 @@ where both ORIGINAL-KEY and SIMULATED-KEY are key sequences."
     (exwm-input--set-simulation-keys simulation-keys)))
 
 ;;;###autoload
-(cl-defun exwm-input-send-simulation-key (times)
+(cl-defun exwm-input-send-simulation-key (n)
-  "Fake a key event according to the last input key sequence."
+  "Fake N key events according to the last input key sequence."
   (interactive "p")
   (exwm--log)
   (unless (derived-mode-p 'exwm-mode)
     (cl-return-from exwm-input-send-simulation-key))
   (let ((keys (gethash (this-single-command-keys)
                        exwm-input--simulation-keys)))
-    (dotimes (_ times)
+    (dotimes (_ n)
       (dolist (key keys)
         (exwm-input--fake-key key)))))
 

exwm-randr.el

@@ -264,7 +264,7 @@ In a mirroring setup some monitors overlap and should be treated as one."
       (run-hooks 'exwm-randr-refresh-hook))))
 
 (defun exwm-randr--on-ScreenChangeNotify (data _synthetic)
-  "Handle `ScreenChangeNotify' event.
+  "Handle `ScreenChangeNotify' event with DATA.
 
 Run `exwm-randr-screen-change-hook' (usually user scripts to configure RandR)."
   (exwm--log)
@@ -276,7 +276,7 @@ Run `exwm-randr-screen-change-hook' (usually user scripts to configure RandR)."
         (run-hooks 'exwm-randr-screen-change-hook)))))
 
 (defun exwm-randr--on-Notify (data _synthetic)
-  "Handle `CrtcChangeNotify' and `OutputChangeNotify' events.
+  "Handle `CrtcChangeNotify' and `OutputChangeNotify' events with DATA.
 
 Refresh when any CRTC/output changes."
   (exwm--log)
@@ -296,7 +296,7 @@ Refresh when any CRTC/output changes."
             (setq exwm-randr--last-timestamp timestamp)))))))
 
 (defun exwm-randr--on-ConfigureNotify (data _synthetic)
-  "Handle `ConfigureNotify' event.
+  "Handle `ConfigureNotify' event with DATA.
 
 Refresh when any RandR 1.5 monitor changes."
   (exwm--log)

exwm-xim.el

@@ -269,7 +269,7 @@ this client."
       (xcb:flush exwm-xim--conn))))
 
 (cl-defun exwm-xim--on-ClientMessage (data _synthetic)
-  "Handle ClientMessage event on IMS communication window (request).
+  "Handle ClientMessage event DATA on IMS communication window (request).
 
 Such events would be received when clients request for _XIM_PROTOCOL.
 The actual XIM request is in client message data or a property."

exwm.el

@@ -139,7 +139,7 @@ After this time, the server will be killed.")
   "Restart EXWM."
   (interactive)
   (exwm--log)
-  (when (exwm--confirm-kill-emacs "Restart?" 'no-check)
+  (when (exwm--confirm-kill-emacs "Restart" 'no-check)
     (let* ((attr (process-attributes (emacs-pid)))
            (args (cdr (assq 'args attr)))
            (ppid (cdr (assq 'ppid attr)))
@@ -976,7 +976,10 @@ FRAME, if given, indicates the X display EXWM should manage."
 
 ;;;###autoload
 (defun exwm-enable (&optional undo)
-  "Enable/Disable EXWM."
+  "Enable/Disable EXWM.
+Optional argument UNDO may be either of the following symbols:
+- `undo' prevents reinitialization.
+- `undo-all' attempts to revert all hooks and advice."
   (exwm--log "%s" undo)
   (pcase undo
     (`undo                              ;prevent reinitialization
@@ -1062,7 +1065,7 @@ FUNCTION is the function to be evaluated, ARGS are the arguments."
   ;; This is invoked instead of `save-buffers-kill-emacs' (C-x C-c) on client
   ;; frames.
   (if (exwm--terminal-p)
-      (exwm--confirm-kill-emacs "Kill terminal?")
+      (exwm--confirm-kill-emacs "Kill terminal")
     t))
 
 (defun exwm--confirm-kill-emacs (prompt &optional force)
@@ -1087,7 +1090,7 @@ If FORCE is any other non-nil value, force killing of Emacs."
             (`break (y-or-n-p prompt))
             (x x)))
          (t
-          (yes-or-no-p (format "[EXWM] %d X window(s) will be destroyed.  %s"
+          (yes-or-no-p (format "[EXWM] %d X window(s) will be destroyed.  %s?"
                                (length exwm--id-buffer-alist) prompt))))
     ;; Run `kill-emacs-hook' (`server-force-stop' excluded) before Emacs
     ;; frames are unmapped so that errors (if any) can be visible.