[PATCH 0/5] Document notmuch-pick and some bugfixes

[PATCH 0/5] Document notmuch-pick and some bugfixes

[Mark Walters]

This adds some documentation to all the defvars in notmuch-pick and to
the notmuch-pick function itself (as suggested by David in
id:87li5rtvbh.fsf@zancas.localnet. This series replaces
id:1372627117-31188-1-git-send-email-markwalters1009@gmail.com but
does still need to be applied on top of the main series there (because
it documents the pick function as it is after that change).

When documenting the defvars I found some trivial bugs: the most
serious being the wrong variable name being made buffer-local. This is
less serious than it could be as this variable was just used to try
and avoid closing the message pane if the user had loaded a different
buffer into it.

The other "bugs" were defvars for variables which are no longer
used. In one case a moderate amount of effort was made passing this
unused variable around so the patch to remove it is not tiny and thus
its removal is delayed until a followup series.

Finally, when looking at which functions did not have docstrings (some
still need to be added after this series) I found an unused historical
function so remove that too.

Best wishes

Mark



Mark Walters (5):
  contrib: pick: add a docstring for the main notmuch-pick function
  contrib: pick: add docstrings to all defvars
  contrib: pick: bugfix: make the right variable buffer-local
  contrib: pick: remove unused variable
  contrib: pick: remove unused function

 contrib/notmuch-pick/notmuch-pick.el |   71 ++++++++++++++++++++-------------
 1 files changed, 43 insertions(+), 28 deletions(-)

-- 
1.7.9.1

[PATCH 1/5] contrib: pick: add a docstring for the main notmuch-pick function

[Mark Walters]

---
 contrib/notmuch-pick/notmuch-pick.el |   14 +++++++++++++-
 1 files changed, 13 insertions(+), 1 deletions(-)

diff --git a/contrib/notmuch-pick/notmuch-pick.el b/contrib/notmuch-pick/notmuch-pick.el
index 11b5058..287c3e5 100644
--- a/contrib/notmuch-pick/notmuch-pick.el
+++ b/contrib/notmuch-pick/notmuch-pick.el
@@ -817,7 +817,19 @@ Complete list of currently available key bindings:
 
 
 (defun notmuch-pick (&optional query query-context target buffer-name open-target)
-  "Run notmuch pick with the given `query' and display the results"
+  "Run notmuch pick with the given `query' and display the results.
+
+The arguments are:
+  QUERY: the main query. This can be any query but in many cases will be
+      a single thread. If nil this is read interactively from the minibuffer.
+  QUERY-CONTEXT: is an additional term for the query. The query used
+      is QUERY and QUERY-CONTEXT unless that does not match any messages
+      in which case we fall back to just QUERY.
+  TARGET: A message ID (with the id: prefix) that will be made
+      current if it appears in the pick results.
+  BUFFER-NAME: the name of the buffer to show the pick tree. If
+      it is nil \"*notmuch-pick\" followed by QUERY is used.
+  OPEN-TARGET: If TRUE open the target message in the message pane."
   (interactive "sNotmuch pick: ")
   (if (null query)
       (setq query (notmuch-read-query "Notmuch pick: ")))
-- 
1.7.9.1

[PATCH 2/5] contrib: pick: add docstrings to all defvars

[Mark Walters]

---
 contrib/notmuch-pick/notmuch-pick.el |   45 ++++++++++++++++++++++-----------
 1 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/contrib/notmuch-pick/notmuch-pick.el b/contrib/notmuch-pick/notmuch-pick.el
index 287c3e5..cce3cb7 100644
--- a/contrib/notmuch-pick/notmuch-pick.el
+++ b/contrib/notmuch-pick/notmuch-pick.el
@@ -146,35 +146,50 @@
   :group 'notmuch-pick
   :group 'notmuch-faces)
 
-(defvar notmuch-pick-previous-subject "")
+(defvar notmuch-pick-previous-subject
+  "The subject of the most recent result shown during the async display")
 (make-variable-buffer-local 'notmuch-pick-previous-subject)
 
-;; The basic query i.e. the key part of the search request.
-(defvar notmuch-pick-basic-query nil)
+(defvar notmuch-pick-basic-query nil
+  "A buffer local copy of argument query to the function notmuch-pick")
 (make-variable-buffer-local 'notmuch-pick-basic-query)
-;; The context of the search: i.e., useful but can be dropped.
-(defvar notmuch-pick-query-context nil)
+
+(defvar notmuch-pick-query-context nil
+  "A buffer local copy of argument query-context to the function notmuch-pick")
 (make-variable-buffer-local 'notmuch-pick-query-context)
-(defvar notmuch-pick-target-msg nil)
+
+(defvar notmuch-pick-target-msg nil
+  "A buffer local copy of argument target to the function notmuch-pick")
 (make-variable-buffer-local 'notmuch-pick-target-msg)
-(defvar notmuch-pick-open-target nil)
+
+(defvar notmuch-pick-open-target nil
+  "A buffer local copy of argument open-target to the function notmuch-pick")
 (make-variable-buffer-local 'notmuch-pick-open-target)
-(defvar notmuch-pick-buffer-name nil)
+
+(defvar notmuch-pick-buffer-name nil
+  "A buffer local copy of argument buffer-name to the function notmuch-pick")
 (make-variable-buffer-local 'notmuch-pick-buffer-name)
-;; This variable is the window used for the message pane. It is set
-;; in both the parent pick buffer and the child show buffer. It is
-;; used to try and close the message pane when quitting pick or the
-;; child show buffer.
-(defvar notmuch-pick-message-window nil)
+
+(defvar notmuch-pick-message-window nil
+  "The window of the message pane.
+
+It is set in both the pick buffer and the child show buffer. It
+is used to try and close the message pane when quitting pick or
+the child show buffer.")
 (make-variable-buffer-local 'notmuch-pick-message-window)
 (put 'notmuch-pick-message-window 'permanent-local t)
-(defvar notmuch-pick-message-buffer nil)
+
+(defvar notmuch-pick-message-buffer nil
+  "The buffer name of the show buffer in the message pane.
+
+This is used to try and make sure we don't close the message pane
+if the user has loaded a different buffer in that window.")
 (make-variable-buffer-local 'notmuch-pick-message-buffer-name)
 (put 'notmuch-pick-message-buffer-name 'permanent-local t)
+
 (defvar notmuch-pick-process-state nil
   "Parsing state of the search process filter.")
 
-
 (defvar notmuch-pick-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key map [mouse-1] 'notmuch-pick-show-message)
-- 
1.7.9.1

[PATCH 3/5] contrib: pick: bugfix: make the right variable buffer-local

[Mark Walters]

The variable notmuch-pick-message-buffer should be buffer local but
instead notmuch-pick-message-buffer-name (a non-existent variable) was
made buffer local.
---
 contrib/notmuch-pick/notmuch-pick.el |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/contrib/notmuch-pick/notmuch-pick.el b/contrib/notmuch-pick/notmuch-pick.el
index cce3cb7..2981508 100644
--- a/contrib/notmuch-pick/notmuch-pick.el
+++ b/contrib/notmuch-pick/notmuch-pick.el
@@ -184,8 +184,8 @@ the child show buffer.")
 
 This is used to try and make sure we don't close the message pane
 if the user has loaded a different buffer in that window.")
-(make-variable-buffer-local 'notmuch-pick-message-buffer-name)
-(put 'notmuch-pick-message-buffer-name 'permanent-local t)
+(make-variable-buffer-local 'notmuch-pick-message-buffer)
+(put 'notmuch-pick-message-buffer 'permanent-local t)
 
 (defvar notmuch-pick-process-state nil
   "Parsing state of the search process filter.")
-- 
1.7.9.1

[PATCH 4/5] contrib: pick: remove unused variable

[Mark Walters]

This variable was needed at one point for the async parser but is not
needed anymore.
---
 contrib/notmuch-pick/notmuch-pick.el |    3 ---
 1 files changed, 0 insertions(+), 3 deletions(-)

diff --git a/contrib/notmuch-pick/notmuch-pick.el b/contrib/notmuch-pick/notmuch-pick.el
index 2981508..25ea4c2 100644
--- a/contrib/notmuch-pick/notmuch-pick.el
+++ b/contrib/notmuch-pick/notmuch-pick.el
@@ -187,9 +187,6 @@ if the user has loaded a different buffer in that window.")
 (make-variable-buffer-local 'notmuch-pick-message-buffer)
 (put 'notmuch-pick-message-buffer 'permanent-local t)
 
-(defvar notmuch-pick-process-state nil
-  "Parsing state of the search process filter.")
-
 (defvar notmuch-pick-mode-map
   (let ((map (make-sparse-keymap)))
     (define-key map [mouse-1] 'notmuch-pick-show-message)
-- 
1.7.9.1

[PATCH 5/5] contrib: pick: remove unused function

[Mark Walters]

The function notmuch-pick-show-error was used before Austin's improved
error handling. It is now redundant so remove.
---
 contrib/notmuch-pick/notmuch-pick.el |    9 ---------
 1 files changed, 0 insertions(+), 9 deletions(-)

diff --git a/contrib/notmuch-pick/notmuch-pick.el b/contrib/notmuch-pick/notmuch-pick.el
index 25ea4c2..7c313e7 100644
--- a/contrib/notmuch-pick/notmuch-pick.el
+++ b/contrib/notmuch-pick/notmuch-pick.el
@@ -764,15 +764,6 @@ Complete list of currently available key bindings:
 		      (insert (format " (process returned %d)" exit-status)))
 		    (insert "\n")))))))))
 
-
-(defun notmuch-pick-show-error (string &rest objects)
-  (save-excursion
-    (goto-char (point-max))
-    (insert "Error: Unexpected output from notmuch search:\n")
-    (insert (apply #'format string objects))
-    (insert "\n")))
-
-
 (defun notmuch-pick-process-filter (proc string)
   "Process and filter the output of \"notmuch show\" (for pick)"
   (let ((results-buf (process-buffer proc))
-- 
1.7.9.1

Re: [PATCH 0/5] Document notmuch-pick and some bugfixes

[David Bremner]

Mark Walters <markwalters1009@gmail.com> writes:

> This adds some documentation to all the defvars in notmuch-pick and to
> the notmuch-pick function itself (as suggested by David in
> id:87li5rtvbh.fsf@zancas.localnet. This series replaces
> id:1372627117-31188-1-git-send-email-markwalters1009@gmail.com but
> does still need to be applied on top of the main series there (because
> it documents the pick function as it is after that change).

Pushed,

d