From 692acdf9da2ca93d46259ca31780ed632c2975c4 Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Sun, 10 Jan 2021 15:01:01 +0100 Subject: [PATCH] emacs: various doc-string improvements --- 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 @@ postponing and resuming a message." :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 @@ 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 diff --git a/emacs/notmuch-maildir-fcc.el b/emacs/notmuch-maildir-fcc.el index c6bdd769..c635284e 100644 --- a/emacs/notmuch-maildir-fcc.el +++ b/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'. - -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 @@ 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 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 @@ 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 -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 @@ 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 -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 @@ 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 -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 @@ the messages that were tagged." ;;; 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 @@ 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 -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 @@ 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 -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 @@ 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 -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 c4ee9e63..f8c97c5d 100644 --- a/emacs/notmuch.el +++ b/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 -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))) @@ -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 -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 @@ -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 -`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.43.0