Re: [PATCH] emacs: Mention race condition safety in user visible documentation

[Michal Sojka <sojkam1@fel.cvut.cz>]

On Tue, 21 Feb 2012, Mark Walters wrote:
> On Sun, 19 Feb 2012 08:33:00 +0100, Michal Sojka <sojkam1@fel.cvut.cz> wrote:
> > On Sun, 19 Feb 2012, Jani Nikula wrote:
> > > On Feb 19, 2012 12:44 AM, "Michal Sojka" <sojkam1@fel.cvut.cz> wrote:
> > > >
> > > > After recent rework of a/A/x/X key bindings, the important paragraph in
> > > > documentation of `notmuch-show-archive-thread' stayed hidden from users,
> > > > because no key is bound to this function.
> > > >
> > > > This patch copies the important paragraph to the documentation of
> > > > functions currently bound to keys.
> > > 
> > > Hi Michal, this was discussed earlier, and Dmitry convinced me that the
> > > code does exactly what the user expects it to do (archives only the
> > > messages in the buffer) so it would be unnecessary and confusing to have
> > > this documentation. It could be added as a comment for developers I
> > > guess.
> > 
> > I'm not sure. As a developer, I'm used to think about race conditions
> > and the mentioned documentation sounds very racy to me. I guess a lot of
> > other notmuch users are developers who may think the same.
> > 
> > > >  (defun notmuch-show-archive-thread-then-next ()
> > > > -  "Archive each message in thread, then show next thread from search."
> > 
> > What about changing it to "Archive each message in the current buffer, ..."?
> 
> I like this suggested wording (or perhaps "Archive all messages in the
> current buffer, ..."). I do not think `Archive each message in thread' is
> completely clear (is the thread the thread as it is now or as it was
> then).

OK, at least one supporter here :) The updated patch follows:

-- >8 --
Subject: [PATCH] emacs: Clarify description of thread manipulating functions

It is not clear whether the term "thread" refers to the thread in the
database or to the thread currently shown in a buffer. Those two
meanings may refer to different sets of messages, e.g. when a new email
is added to the database while the buffer shows the state before the new
email arrived.

This patch replaces the term thread with the term current buffer, which
is hopefully less ambiguous.
---
 emacs/notmuch-show.el |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
index aa9ccee..3515d03 100644
--- a/emacs/notmuch-show.el
+++ b/emacs/notmuch-show.el
@@ -1628,7 +1628,7 @@ TAG-CHANGES is a list of tag operations for `notmuch-tag'."
     (apply 'notmuch-show-tag-message tag-changes)))
 
 (defun notmuch-show-tag-all (&rest tag-changes)
-  "Change tags for all messages in the current thread.
+  "Change tags for all messages in the current buffer.
 
 TAG-CHANGES is a list of tag operations for `notmuch-tag'."
   (interactive (notmuch-read-tag-changes nil notmuch-show-thread-id))
@@ -1721,13 +1721,13 @@ buffer."
     (notmuch-show-tag-all (concat op "inbox"))))
 
 (defun notmuch-show-archive-thread-then-next ()
-  "Archive each message in thread, then show next thread from search."
+  "Archive all messages in the current buffer, then show next thread from search."
   (interactive)
   (notmuch-show-archive-thread)
   (notmuch-show-next-thread t))
 
 (defun notmuch-show-archive-thread-then-exit ()
-  "Archive each message in thread, then exit back to search results."
+  "Archive all messages in the current buffer, then exit back to search results."
   (interactive)
   (notmuch-show-archive-thread)
   (notmuch-show-next-thread))
-- 
1.7.7.3