]> git.notmuchmail.org Git - notmuch/blobdiff - emacs/notmuch.el
emacs: various doc-string improvements
[notmuch] / emacs / notmuch.el
index ba9488ca42d5b80f1e69a21843718274c063f96a..f8c97c5df85db83a382f5e6b0a259b9135e4ee2f 100644 (file)
@@ -179,7 +179,7 @@ there will be called at other points of notmuch execution."
   (let ((map (make-sparse-keymap)))
     (set-keymap-parent map notmuch-common-keymap)
     (define-key map "x" 'notmuch-bury-or-kill-this-buffer)
-    (define-key map (kbd "<DEL>") 'notmuch-search-scroll-down)
+    (define-key map (kbd "DEL") 'notmuch-search-scroll-down)
     (define-key map "b" 'notmuch-search-scroll-down)
     (define-key map " " 'notmuch-search-scroll-up)
     (define-key map "<" 'notmuch-search-first-thread)
@@ -232,7 +232,7 @@ there will be called at other points of notmuch execution."
 (defvar notmuch-search-target-thread)
 (defvar notmuch-search-target-line)
 
-(defvar notmuch-search-disjunctive-regexp      "\\<[oO][rR]\\>")
+(defvar notmuch-search-disjunctive-regexp "\\<[oO][rR]\\>")
 
 ;;; Movement
 
@@ -494,7 +494,7 @@ If BARE is set then do not prefix with \"thread:\"."
 (defun notmuch-search-find-stable-query ()
   "Return the stable queries for the current thread.
 
-This returns a list (MATCHED-QUERY UNMATCHED-QUERY) for the
+Return a list (MATCHED-QUERY UNMATCHED-QUERY) for the
 matched and unmatched messages in the current thread."
   (plist-get (notmuch-search-get-result) :query))
 
@@ -599,7 +599,7 @@ thread."
 (defun notmuch-search-interactive-tag-changes (&optional initial-input)
   "Prompt for tag changes for the current thread or region.
 
-Returns (TAG-CHANGES REGION-BEGIN REGION-END)."
+Return (TAG-CHANGES REGION-BEGIN REGION-END)."
   (pcase-let ((`(,beg ,end) (notmuch-interactive-region)))
     (list (notmuch-read-tag-changes (notmuch-search-get-tags-region beg end)
                                    (if (= beg end) "Tag thread" "Tag region")
@@ -693,7 +693,7 @@ of the result."
                          (min init-point (- new-end 1)))))
        (goto-char new-point)))))
 
-(defun notmuch-search-process-sentinel (proc msg)
+(defun notmuch-search-process-sentinel (proc _msg)
   "Add a message to let user know when \"notmuch search\" exits."
   (let ((buffer (process-buffer proc))
        (status (process-status proc))
@@ -896,8 +896,7 @@ sets the :orig-tag property."
   "Process and filter the output of \"notmuch search\"."
   (let ((results-buf (process-buffer proc))
        (parse-buf (process-get proc 'parse-buf))
-       (inhibit-read-only t)
-       done)
+       (inhibit-read-only t))
     (when (buffer-live-p results-buf)
       (with-current-buffer parse-buf
        ;; Insert new data
@@ -951,40 +950,39 @@ See `notmuch-tag' for information on the format of TAG-CHANGES."
   "Read a notmuch-query from the minibuffer with completion.
 
 PROMPT is the string to prompt with."
-  (let*
-      ((all-tags
-       (mapcar (lambda (tag) (notmuch-escape-boolean-term tag))
-               (process-lines notmuch-command "search" "--output=tags" "*")))
-       (completions
-       (append (list "folder:" "path:" "thread:" "id:" "date:" "from:" "to:"
-                     "subject:" "attachment:")
-               (mapcar (lambda (tag) (concat "tag:" tag)) all-tags)
-               (mapcar (lambda (tag) (concat "is:" tag)) all-tags)
-               (mapcar (lambda (mimetype) (concat "mimetype:" mimetype))
-                       (mailcap-mime-types)))))
-    (let ((keymap (copy-keymap minibuffer-local-map))
-         (current-query (cl-case major-mode
-                          (notmuch-search-mode (notmuch-search-get-query))
-                          (notmuch-show-mode (notmuch-show-get-query))
-                          (notmuch-tree-mode (notmuch-tree-get-query))))
-         (minibuffer-completion-table
-          (completion-table-dynamic
-           (lambda (string)
-             ;; generate a list of possible completions for the current input
-             (cond
-              ;; this ugly regexp is used to get the last word of the input
-              ;; possibly preceded by a '('
-              ((string-match "\\(^\\|.* (?\\)\\([^ ]*\\)$" string)
-               (mapcar (lambda (compl)
-                         (concat (match-string-no-properties 1 string) compl))
-                       (all-completions (match-string-no-properties 2 string)
-                                        completions)))
-              (t (list string)))))))
-      ;; this was simpler than convincing completing-read to accept spaces:
-      (define-key keymap (kbd "TAB") 'minibuffer-complete)
-      (let ((history-delete-duplicates t))
-       (read-from-minibuffer prompt nil keymap nil
-                             'notmuch-search-history current-query nil)))))
+  (let* ((all-tags
+         (mapcar (lambda (tag) (notmuch-escape-boolean-term tag))
+                 (process-lines notmuch-command "search" "--output=tags" "*")))
+        (completions
+         (append (list "folder:" "path:" "thread:" "id:" "date:" "from:" "to:"
+                       "subject:" "attachment:")
+                 (mapcar (lambda (tag) (concat "tag:" tag)) all-tags)
+                 (mapcar (lambda (tag) (concat "is:" tag)) all-tags)
+                 (mapcar (lambda (mimetype) (concat "mimetype:" mimetype))
+                         (mailcap-mime-types))))
+        (keymap (copy-keymap minibuffer-local-map))
+        (current-query (cl-case major-mode
+                         (notmuch-search-mode (notmuch-search-get-query))
+                         (notmuch-show-mode (notmuch-show-get-query))
+                         (notmuch-tree-mode (notmuch-tree-get-query))))
+        (minibuffer-completion-table
+         (completion-table-dynamic
+          (lambda (string)
+            ;; Generate a list of possible completions for the current input.
+            (cond
+             ;; This ugly regexp is used to get the last word of the input
+             ;; possibly preceded by a '('.
+             ((string-match "\\(^\\|.* (?\\)\\([^ ]*\\)$" string)
+              (mapcar (lambda (compl)
+                        (concat (match-string-no-properties 1 string) compl))
+                      (all-completions (match-string-no-properties 2 string)
+                                       completions)))
+             (t (list string)))))))
+    ;; This was simpler than convincing completing-read to accept spaces:
+    (define-key keymap (kbd "TAB") 'minibuffer-complete)
+    (let ((history-delete-duplicates t))
+      (read-from-minibuffer prompt nil keymap nil
+                           'notmuch-search-history current-query nil))))
 
 (defun notmuch-search-get-query ()
   "Return the current query in this search buffer."
@@ -1043,12 +1041,12 @@ the configured default sort order."
                     (if oldest-first
                         "--sort=oldest-first"
                       "--sort=newest-first")
-                    query))
-             ;; Use a scratch buffer to accumulate partial output.
-             ;; This buffer will be killed by the sentinel, which
-             ;; should be called no matter how the process dies.
-             (parse-buf (generate-new-buffer " *notmuch search parse*")))
-         (process-put proc 'parse-buf parse-buf)
+                    query)))
+         ;; Use a scratch buffer to accumulate partial output.
+         ;; This buffer will be killed by the sentinel, which
+         ;; should be called no matter how the process dies.
+         (process-put proc 'parse-buf
+                      (generate-new-buffer " *notmuch search parse*"))
          (set-process-filter proc 'notmuch-search-process-filter)
          (set-process-query-on-exit-flag proc nil))))
     (run-hooks 'notmuch-search-hook)))
@@ -1103,10 +1101,10 @@ current search results AND the additional query string provided."
                    notmuch-search-oldest-first)))
 
 (defun notmuch-search-filter-by-tag (tag)
-  "Filter the current search results based on a single tag.
+  "Filter the current search results based on a single TAG.
 
-Runs a new search matching only messages that match both the
-current search results AND that are tagged with the given tag."
+Run a new search matching only messages that match the current
+search results and that are also tagged with the given TAG."
   (interactive
    (list (notmuch-select-tag-with-completion "Filter by tag: "
                                             notmuch-search-query-string)))
@@ -1126,7 +1124,7 @@ current search results AND that are tagged with the given tag."
   (notmuch-hello))
 
 (defun notmuch-interesting-buffer (b)
-  "Is the current buffer of interest to a notmuch user?"
+  "Whether the current buffer's major-mode is a notmuch mode."
   (with-current-buffer b
     (memq major-mode '(notmuch-show-mode
                       notmuch-search-mode
@@ -1138,8 +1136,8 @@ current search results AND that are tagged with the given tag."
 (defun notmuch-cycle-notmuch-buffers ()
   "Cycle through any existing notmuch buffers (search, show or hello).
 
-If the current buffer is the only notmuch buffer, bury it. If no
-notmuch buffers exist, run `notmuch'."
+If the current buffer is the only notmuch buffer, bury it.
+If no notmuch buffers exist, run `notmuch'."
   (interactive)
   (let (start first)
     ;; If the current buffer is a notmuch buffer, remember it and then
@@ -1164,15 +1162,13 @@ notmuch buffers exist, run `notmuch'."
 
 (defun notmuch-search-imenu-prev-index-position-function ()
   "Move point to previous message in notmuch-search buffer.
-This function is used as a value for
-`imenu-prev-index-position-function'."
+Used as`imenu-prev-index-position-function' in notmuch buffers."
   (notmuch-search-previous-thread))
 
 (defun notmuch-search-imenu-extract-index-name-function ()
   "Return imenu name for line at point.
-This function is used as a value for
-`imenu-extract-index-name-function'.  Point should be at the
-beginning of the line."
+Used as `imenu-extract-index-name-function' in notmuch buffers.
+Point should be at the beginning of the line."
   (let ((subject (notmuch-search-find-subject))
        (author (notmuch-search-find-authors)))
     (format "%s (%s)" subject author)))