From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id AI8+ClYJ+1/heAAA0tVLHw (envelope-from ) for ; Sun, 10 Jan 2021 14:04:06 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id UCo0BlYJ+19sRgAAbx9fmQ (envelope-from ) for ; Sun, 10 Jan 2021 14:04:06 +0000 Received: from mail.notmuchmail.org (nmbug.tethera.net [IPv6:2607:5300:201:3100::1657]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (2048 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id BDB37940276 for ; Sun, 10 Jan 2021 14:04:05 +0000 (UTC) Received: from nmbug.tethera.net (localhost [127.0.0.1]) by mail.notmuchmail.org (Postfix) with ESMTP id 0D1B42BF62; Sun, 10 Jan 2021 09:02:07 -0500 (EST) Received: from mail.hostpark.net (mail.hostpark.net [212.243.197.30]) by mail.notmuchmail.org (Postfix) with ESMTPS id 97AA429E0C for ; Sun, 10 Jan 2021 09:01:18 -0500 (EST) Received: from localhost (localhost [127.0.0.1]) by mail.hostpark.net (Postfix) with ESMTP id 81F131666A for ; Sun, 10 Jan 2021 15:01:14 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=bernoul.li; h= content-transfer-encoding:mime-version:references:in-reply-to :x-mailer:message-id:date:date:subject:subject:from:from :received:received; s=sel2011a; t=1610287274; bh=gyIy46PLSPdIVvo DX/fQgiUibNVL2tHehwoB07IK5dw=; b=1E1S2ata3i/bdMBbeyZ6EM7yqIF/Gt5 wXJDyiXcz2DuF2wxkkb3OGQdoDtap7EWYX0sByrEhpBW4sfIylOjyJVToVIDanD8 WpC/kMDdRQznZfuZ5uaJXqnf2YCIORcbPz/t96rVT0y3aM004qwN5J1Wg3AfCJ6L jNe5DvYUpyR4= X-Virus-Scanned: by Hostpark/NetZone Mailprotection at hostpark.net Received: from mail.hostpark.net ([127.0.0.1]) by localhost (mail0.hostpark.net [127.0.0.1]) (amavisd-new, port 10224) with ESMTP id 2vJpBVi25UD8 for ; Sun, 10 Jan 2021 15:01:14 +0100 (CET) Received: from customer (localhost [127.0.0.1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mail.hostpark.net (Postfix) with ESMTPSA id 30C20166AB for ; Sun, 10 Jan 2021 15:01:14 +0100 (CET) From: Jonas Bernoulli To: notmuch@notmuchmail.org Subject: [PATCH v2 25/36] emacs: various doc-string improvements Date: Sun, 10 Jan 2021 15:01:01 +0100 Message-Id: <20210110140112.25930-26-jonas@bernoul.li> X-Mailer: git-send-email 2.29.1 In-Reply-To: <20210110140112.25930-1-jonas@bernoul.li> References: <20201214162401.19569-1-jonas@bernoul.li> <20210110140112.25930-1-jonas@bernoul.li> MIME-Version: 1.0 Message-ID-Hash: 4IG2XOKRZWOKHVJETUNBMHZUKSKZUY26 X-Message-ID-Hash: 4IG2XOKRZWOKHVJETUNBMHZUKSKZUY26 X-MailFrom: jonas@bernoul.li X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-notmuch.notmuchmail.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.1 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Help: List-Post: List-Subscribe: List-Unsubscribe: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: 0.06 Authentication-Results: aspmx1.migadu.com; dkim=fail (body hash did not verify) header.d=bernoul.li header.s=sel2011a header.b=1E1S2ata; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 2607:5300:201:3100::1657 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Migadu-Queue-Id: BDB37940276 X-Spam-Score: 0.06 X-Migadu-Scanner: scn0.migadu.com X-TUID: ijur+1Rrqcgn --- 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 b3c2570e..efbb37f1 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 c4ee9e63..f8c97c5d 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") @@ -1101,10 +1101,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))) @@ -1124,7 +1124,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 @@ -1136,8 +1136,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 @@ -1162,15 +1162,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