[PATCH 25/32] emacs: various doc-string improvements

[Jonas Bernoulli <jonas@bernoul.li>]

---
 emacs/notmuch-draft.el       | 12 ++++++-----
 emacs/notmuch-maildir-fcc.el | 21 +++++++++---------
 emacs/notmuch-mua.el         |  9 ++++----
 emacs/notmuch-tag.el         | 41 ++++++++++++++++++------------------
 emacs/notmuch-tree.el        | 10 ++++-----
 emacs/notmuch.el             | 24 ++++++++++-----------
 6 files changed, 59 insertions(+), 58 deletions(-)

diff --git a/emacs/notmuch-draft.el b/emacs/notmuch-draft.el
index 8af04598..bc688434 100644
--- a/emacs/notmuch-draft.el
+++ b/emacs/notmuch-draft.el
@@ -77,9 +77,11 @@ (defcustom notmuch-draft-quoted-tags '()
   :group 'notmuch-send)
 
 (defcustom notmuch-draft-save-plaintext 'ask
-  "Should notmuch save/postpone in plaintext messages that seem
-like they are intended to be sent encrypted
-(i.e with an mml encryption tag in it)."
+  "Whether to allow saving plaintext when it seems encryption is intended.
+When a message contains mml tags, then that suggest it is
+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 @@ (defun notmuch-draft-unquote-some-mml ()
 	(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
diff --git a/emacs/notmuch-maildir-fcc.el b/emacs/notmuch-maildir-fcc.el
index 945a66fc..0000863d 100644
--- a/emacs/notmuch-maildir-fcc.el
+++ b/emacs/notmuch-maildir-fcc.el
@@ -90,10 +90,8 @@ (defcustom notmuch-maildir-use-notmuch-insert t
 (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'.
-
-Originally intended to be use a hook function, but now called directly
-by notmuch-mua-mail."
+If the Fcc header is already set, then keep it as-is.
+Otherwise set it according to `notmuch-fcc-dirs'."
   (let ((subdir
 	 (cond
 	  ((or (not notmuch-fcc-dirs)
@@ -153,8 +151,9 @@ (defmacro with-temporary-notmuch-message-buffer (&rest body)
        ,@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 @@ (defun notmuch-maildir-fcc-move-tmp-to-cur (destdir msg-id &optional mark-seen)
 (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 needed."
+If that fails, then offer the user a chance to correct the header
+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 @@ (defun notmuch-maildir-fcc-file-fcc (fcc-header)
 	     (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
-non-nil, it will write it to cur/, and mark it as read. It should
-return t if successful, and nil otherwise."
+  "Write the current buffer to maildir destdir.
+
+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)
diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el
index 4a08e8a7..2e4dc71a 100644
--- a/emacs/notmuch-mua.el
+++ b/emacs/notmuch-mua.el
@@ -99,7 +99,7 @@ (defcustom notmuch-always-prompt-for-sender nil
   :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 @@ (defcustom notmuch-mua-attachment-regexp
 ;;; Various functions
 
 (defun notmuch-mua-attachment-check ()
-  "Signal an error if the message text indicates that an
-attachment is expected but no MML referencing an attachment is
-found.
+  "Signal an error an attachement is expected but missing.
+
+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
diff --git a/emacs/notmuch-tag.el b/emacs/notmuch-tag.el
index 0c9a32ac..c006026c 100644
--- a/emacs/notmuch-tag.el
+++ b/emacs/notmuch-tag.el
@@ -141,20 +141,23 @@ (defcustom 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
-lists of formatting expressions.  The first entry whose car
-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
-that tag name (if it contains special regexp characters like
-\".\" or \"*\", these have to be escaped).  The cdr of the
-matching entry gives a list of Elisp expressions that modify the
-tag.  If the list is empty, the tag will simply be hidden.
-Otherwise, each expression will be evaluated in order: for the
-first expression, the variable `tag' will be bound to the tag
-name; for each later expression, the variable `tag' will be bound
-to the result of the previous expression.  In this way, each
+This is an association list of the form ((MATCH EXPR...)...),
+mapping tag name regexps to lists of formatting expressions.
+
+The first entry whose MATCH regexp-matches a tag is used to
+format that tag.  The regexp is implicitly anchored, so to match
+a literal tag name, just use that tag name (if it contains
+special regexp characters like \".\" or \"*\", these have to be
+escaped).
+
+The cdr of the matching entry gives a list of Elisp expressions
+that modify the tag.  If the list is empty, the tag is simply
+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 @@ (defcustom notmuch-after-tag-hook nil
 ;;; User Input
 
 (defvar notmuch-select-tag-history nil
-  "Variable to store minibuffer history for
-`notmuch-select-tag-with-completion' function.")
+  "Minibuffer history of `notmuch-select-tag-with-completion' function.")
 
 (defvar notmuch-read-tag-changes-history nil
-  "Variable to store minibuffer history for
-`notmuch-read-tag-changes' function.")
+  "Minibuffer history of `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 @@ (defun notmuch-select-tag-with-completion (prompt &rest search-terms)
 (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
-messages to be changed.  These are offered as tag removal
+CURRENT-TAGS is a list of tags that are present on the message
+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
diff --git a/emacs/notmuch-tree.el b/emacs/notmuch-tree.el
index e254593f..a06afc2d 100644
--- a/emacs/notmuch-tree.el
+++ b/emacs/notmuch-tree.el
@@ -791,8 +791,7 @@ (defun notmuch-tree-next-thread-from-search (&optional previous)
       (notmuch-tree-from-search-thread))))
 
 (defun notmuch-tree-next-thread (&optional previous)
-  "Move to the next thread in the current tree or parent search
-results
+  "Move to the next thread in the current tree or parent search results.
 
 If PREVIOUS is non-nil, move to the previous thread in the tree or
 search results instead."
@@ -802,14 +801,13 @@ (defun notmuch-tree-next-thread (&optional previous)
     (notmuch-tree-next-thread-from-search previous)))
 
 (defun notmuch-tree-prev-thread ()
-  "Move to the previous thread in the current tree or parent search
-results"
+  "Move to the previous thread in the current tree or parent search results."
   (interactive)
   (notmuch-tree-next-thread t))
 
 (defun notmuch-tree-thread-mapcar (function)
-  "Iterate through all messages in the current thread
- and call FUNCTION for side effects."
+  "Call FUNCTION for each message in the current thread.
+FUNCTION is called for side effects only."
   (save-excursion
     (notmuch-tree-thread-top)
     (cl-loop collect (funcall function)
diff --git a/emacs/notmuch.el b/emacs/notmuch.el
index 4e975d6a..20d2f095 100644
--- a/emacs/notmuch.el
+++ b/emacs/notmuch.el
@@ -494,7 +494,7 @@ (defun notmuch-search-find-thread-id (&optional bare)
 (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 @@ (defun notmuch-search-get-tags-region (beg end)
 (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")
@@ -1105,10 +1105,10 @@ (defun notmuch-search-filter (query)
 		    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)))
@@ -1128,7 +1128,7 @@ (defun notmuch ()
   (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
@@ -1140,8 +1140,8 @@ (defun notmuch-interesting-buffer (b)
 (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
@@ -1166,15 +1166,13 @@ (defun notmuch-cycle-notmuch-buffers ()
 
 (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)))
-- 
2.29.1