emacs: various doc-string improvements

emacs/notmuch-draft.el

@@ -77,9 +77,11 @@ postponing and resuming a message."
   :group 'notmuch-send)
 
 (defcustom notmuch-draft-save-plaintext 'ask
-  "Should notmuch save/postpone in plaintext messages that seem
+  "Whether to allow saving plaintext when it seems encryption is intended.
-like they are intended to be sent encrypted
+When a message contains mml tags, then that suggest it is
-(i.e with an mml encryption tag in it)."
+intended to be encrypted.  If the user requests that such a
+message is saved locally, then this option controls whether
+that is allowed.  Beside a boolean, this can also be `ask'."
   :type '(radio
 	  (const :tag "Never" nil)
 	  (const :tag "Ask every time" ask)
@@ -146,13 +148,13 @@ Used when a new version is saved, or the message is sent."
 	(insert secure-tag "\n")))))
 
 (defun notmuch-draft--has-encryption-tag ()
-  "Returns t if there is an mml secure tag."
+  "Return non-nil if there is an mml secure tag."
   (save-excursion
     (message-goto-body)
     (re-search-forward notmuch-draft-encryption-tag-regex nil t)))
 
 (defun notmuch-draft--query-encryption ()
-  "Checks if we should save a message that should be encrypted.
+  "Return non-nil if we should save a message that should be encrypted.
 
 `notmuch-draft-save-plaintext' controls the behaviour."
   (cl-case notmuch-draft-save-plaintext

emacs/notmuch-maildir-fcc.el

@@ -90,10 +90,8 @@ directory if it does not exist yet when sending a mail."
 (defun notmuch-fcc-header-setup ()
   "Add an Fcc header to the current message buffer.
 
-Sets the Fcc header based on the values of `notmuch-fcc-dirs'.
+If the Fcc header is already set, then keep it as-is.
-
+Otherwise set it according to `notmuch-fcc-dirs'."
-Originally intended to be use a hook function, but now called directly
-by notmuch-mua-mail."
   (let ((subdir
 	 (cond
 	  ((or (not notmuch-fcc-dirs)
@@ -153,8 +151,9 @@ by notmuch-mua-mail."
        ,@body)))
 
 (defun notmuch-maildir-setup-message-for-saving ()
-  "Setup message for saving. Should be called on a temporary copy.
+  "Setup message for saving.
 
+This should be called on a temporary copy.
 This is taken from the function message-do-fcc."
   (message-encode-message-body)
   (save-restriction
@@ -308,8 +307,8 @@ if successful, nil if not."
 (defun notmuch-maildir-fcc-file-fcc (fcc-header)
   "Write the message to the file specified by FCC-HEADER.
 
-It offers the user a chance to correct the header, or filesystem,
+If that fails, then offer the user a chance to correct the header
-if needed."
+or filesystem."
   (if (notmuch-maildir-fcc-dir-is-maildir-p fcc-header)
       (notmuch-maildir-fcc-write-buffer-to-maildir fcc-header t)
     ;; The fcc-header is not a valid maildir see if the user wants to
@@ -329,9 +328,11 @@ if needed."
 	     (read-from-minibuffer "Fcc header: " fcc-header)))))))
 
 (defun notmuch-maildir-fcc-write-buffer-to-maildir (destdir &optional mark-seen)
-  "Writes the current buffer to maildir destdir. If mark-seen is
+  "Write the current buffer to maildir destdir.
-non-nil, it will write it to cur/, and mark it as read. It should
+
-return t if successful, and nil otherwise."
+If mark-seen is non-nil, then write it to \"cur/\", and mark it
+as read, otherwise write it to \"new/\". Return t if successful,
+and nil otherwise."
   (let ((orig-buffer (buffer-name)))
     (with-temp-buffer
       (insert-buffer-substring orig-buffer)

emacs/notmuch-mua.el

@@ -99,7 +99,7 @@ the From: header is already filled in by notmuch."
   :group 'notmuch-send)
 
 (defgroup notmuch-reply nil
-  "Replying to messages in notmuch"
+  "Replying to messages in notmuch."
   :group 'notmuch)
 
 (defcustom notmuch-mua-cite-function 'message-cite-original
@@ -144,9 +144,10 @@ to `notmuch-mua-send-hook'."
 ;;; Various functions
 
 (defun notmuch-mua-attachment-check ()
-  "Signal an error if the message text indicates that an
+  "Signal an error an attachement is expected but missing.
-attachment is expected but no MML referencing an attachment is
+
-found.
+Signal an error if the message text indicates that an attachment
+is expected but no MML referencing an attachment is found.
 
 Typically this is added to `notmuch-mua-send-hook'."
   (when (and

emacs/notmuch-tag.el

@@ -141,20 +141,23 @@ Used in the default value of `notmuch-tag-formats'."
      (notmuch-tag-format-image-data tag (notmuch-tag-star-icon))))
   "Custom formats for individual tags.
 
-This is an association list that maps from tag name regexps to
+This is an association list of the form ((MATCH EXPR...)...),
-lists of formatting expressions.  The first entry whose car
+mapping tag name regexps to lists of formatting expressions.
-regexp-matches a tag will be used to format that tag.  The regexp
+
-is implicitly anchored, so to match a literal tag name, just use
+The first entry whose MATCH regexp-matches a tag is used to
-that tag name (if it contains special regexp characters like
+format that tag.  The regexp is implicitly anchored, so to match
-\".\" or \"*\", these have to be escaped).  The cdr of the
+a literal tag name, just use that tag name (if it contains
-matching entry gives a list of Elisp expressions that modify the
+special regexp characters like \".\" or \"*\", these have to be
-tag.  If the list is empty, the tag will simply be hidden.
+escaped).
-Otherwise, each expression will be evaluated in order: for the
+
-first expression, the variable `tag' will be bound to the tag
+The cdr of the matching entry gives a list of Elisp expressions
-name; for each later expression, the variable `tag' will be bound
+that modify the tag.  If the list is empty, the tag is simply
-to the result of the previous expression.  In this way, each
+hidden.  Otherwise, each expression EXPR is evaluated in order:
+for the first expression, the variable `tag' is bound to the tag
+name; for each later expression, the variable `tag' is bound to
+the result of the previous expression.  In this way, each
 expression can build on the formatting performed by the previous
-expression.  The result of the last expression will displayed in
+expression.  The result of the last expression is displayed in
 place of the tag.
 
 For example, to replace a tag with another string, simply use
@@ -384,17 +387,15 @@ the messages that were tagged."
 ;;; User Input
 
 (defvar notmuch-select-tag-history nil
-  "Variable to store minibuffer history for
+  "Minibuffer history of `notmuch-select-tag-with-completion' function.")
-`notmuch-select-tag-with-completion' function.")
 
 (defvar notmuch-read-tag-changes-history nil
-  "Variable to store minibuffer history for
+  "Minibuffer history of `notmuch-read-tag-changes' function.")
-`notmuch-read-tag-changes' function.")
 
 (defun notmuch-tag-completions (&rest search-terms)
   "Return a list of tags for messages matching SEARCH-TERMS.
 
-Returns all tags if no search terms are given."
+Return all tags if no search terms are given."
   (unless search-terms
     (setq search-terms (list "*")))
   (split-string
@@ -411,8 +412,8 @@ Returns all tags if no search terms are given."
 (defun notmuch-read-tag-changes (current-tags &optional prompt initial-input)
   "Prompt for tag changes in the minibuffer.
 
-CURRENT-TAGS is a list of tags that are present on the message or
+CURRENT-TAGS is a list of tags that are present on the message
-messages to be changed.  These are offered as tag removal
+or messages to be changed.  These are offered as tag removal
 completions.  CURRENT-TAGS may contain duplicates.  PROMPT, if
 non-nil, is the query string to present in the minibuffer.  It
 defaults to \"Tags\".  INITIAL-INPUT, if non-nil, will be the

emacs/notmuch-tree.el

@@ -791,8 +791,7 @@ search results instead."
       (notmuch-tree-from-search-thread))))
 
 (defun notmuch-tree-next-thread (&optional previous)
-  "Move to the next thread in the current tree or parent search
+  "Move to the next thread in the current tree or parent search results.
-results
 
 If PREVIOUS is non-nil, move to the previous thread in the tree or
 search results instead."
@@ -802,14 +801,13 @@ search results instead."
     (notmuch-tree-next-thread-from-search previous)))
 
 (defun notmuch-tree-prev-thread ()
-  "Move to the previous thread in the current tree or parent search
+  "Move to the previous thread in the current tree or parent search results."
-results"
   (interactive)
   (notmuch-tree-next-thread t))
 
 (defun notmuch-tree-thread-mapcar (function)
-  "Iterate through all messages in the current thread
+  "Call FUNCTION for each message in the current thread.
- and call FUNCTION for side effects."
+FUNCTION is called for side effects only."
   (save-excursion
     (notmuch-tree-thread-top)
     (cl-loop collect (funcall function)

emacs/notmuch.el

@@ -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")
@@ -1101,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
+Run a new search matching only messages that match the current
-current search results AND that are tagged with the given tag."
+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)))
@@ -1124,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
@@ -1136,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
+If the current buffer is the only notmuch buffer, bury it.
-notmuch buffers exist, run `notmuch'."
+If no notmuch buffers exist, run `notmuch'."
   (interactive)
   (let (start first)
     ;; If the current buffer is a notmuch buffer, remember it and then
@@ -1162,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
+Used as`imenu-prev-index-position-function' in notmuch buffers."
-`imenu-prev-index-position-function'."
   (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
+Used as `imenu-extract-index-name-function' in notmuch buffers.
-`imenu-extract-index-name-function'.  Point should be at the
+Point should be at the beginning of the line."
-beginning of the line."
   (let ((subject (notmuch-search-find-subject))
 	(author (notmuch-search-find-authors)))
     (format "%s (%s)" subject author)))