partial cleanup of warnings from byte compilation

partial cleanup of warnings from byte compilation

[David Bremner]

This is almost all docstring formatting, except for the last
patch.

This is really just some low hanging fruit, but presumable eliminating
some warnings is better than nothing. The warnings are more annoying
now that native compilation exposes them to every user.

[PATCH 1/4] emacs: update quoting in docstrings

[David Bremner]

The complicated looking escapes are needed to avoid compile time
warnings.  (info "(elisp) Text Quoting Style") for details.
---
 emacs/notmuch-hello.el  |  2 +-
 emacs/notmuch-lib.el    |  6 +++---
 emacs/notmuch-parser.el |  8 ++++----
 emacs/notmuch-print.el  |  4 ++--
 emacs/notmuch-tag.el    | 12 ++++++------
 emacs/notmuch-wash.el   |  2 +-
 6 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index 4662e704..2d4fdc02 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -145,7 +145,7 @@ a plist. Supported properties are
                    or nil. Nil means use the default sort order.
   :search-type     Specify whether to run the search in search-mode,
                    tree mode or unthreaded mode. Set to `tree' to
-                   specify tree mode, 'unthreaded to specify
+                   specify tree mode, \\='unthreaded to specify
                    unthreaded mode, and set to nil (or anything
                    except tree and unthreaded) to specify search
                    mode.
diff --git a/emacs/notmuch-lib.el b/emacs/notmuch-lib.el
index a09f4ab8..14469a90 100644
--- a/emacs/notmuch-lib.el
+++ b/emacs/notmuch-lib.el
@@ -414,9 +414,9 @@ This is similar to `describe-function' for the current major
 mode, but bindings tables are shown with documentation strings
 rather than command names.  By default, this uses the first line
 of each command's documentation string.  A command can override
-this by setting the 'notmuch-doc property of its command symbol.
+this by setting the \\='notmuch-doc property of its command symbol.
 A command that supports a prefix argument can explicitly document
-its prefixed behavior by setting the 'notmuch-prefix-doc property
+its prefixed behavior by setting the \\='notmuch-prefix-doc property
 of its command symbol."
   (interactive)
   (let ((doc (substitute-command-keys
@@ -726,7 +726,7 @@ single element face list."
     (list face)))
 
 (defun notmuch-apply-face (object face &optional below start end)
-  "Combine FACE into the 'face text property of OBJECT between START and END.
+  "Combine FACE into the \\='face text property of OBJECT between START and END.
 
 This function combines FACE with any existing faces between START
 and END in OBJECT.  Attributes specified by FACE take precedence
diff --git a/emacs/notmuch-parser.el b/emacs/notmuch-parser.el
index f04b07c2..710c60e1 100644
--- a/emacs/notmuch-parser.el
+++ b/emacs/notmuch-parser.el
@@ -35,7 +35,7 @@ complete S-expression from the input.  However, it extends this
 with an additional function that requires the next value in the
 input to be a list and descends into it, allowing its elements to
 be read one at a time or further descended into.  Both functions
-can return 'retry to indicate that not enough input is available.
+can return \\='retry to indicate that not enough input is available.
 
 The parser always consumes input from point in the current
 buffer.  Hence, the caller is allowed to delete any data before
@@ -52,10 +52,10 @@ point and may resynchronize after an error by moving point."
 (defun notmuch-sexp-read (sp)
   "Consume and return the value at point in the current buffer.
 
-Returns 'retry if there is insufficient input to parse a complete
+Returns \\='retry if there is insufficient input to parse a complete
 value (though it may still move point over whitespace).  If the
 parser is currently inside a list and the next token ends the
-list, this moves point just past the terminator and returns 'end.
+list, this moves point just past the terminator and returns \\='end.
 Otherwise, this moves point to just past the end of the value and
 returns the value."
   (skip-chars-forward " \n\r\t")
@@ -125,7 +125,7 @@ returns the value."
 (defun notmuch-sexp-begin-list (sp)
   "Parse the beginning of a list value and enter the list.
 
-Returns 'retry if there is insufficient input to parse the
+Returns \\='retry if there is insufficient input to parse the
 beginning of the list.  If this is able to parse the beginning of
 a list, it moves point past the token that opens the list and
 returns t.  Later calls to `notmuch-sexp-read' will return the
diff --git a/emacs/notmuch-print.el b/emacs/notmuch-print.el
index 85fa1f21..8d9f1b08 100644
--- a/emacs/notmuch-print.el
+++ b/emacs/notmuch-print.el
@@ -41,11 +41,11 @@
 ;;; Utility functions
 
 (defun notmuch-print-run-evince (file)
-  "View FILE using 'evince'."
+  "View FILE using `evince'."
   (start-process "evince" nil "evince" file))
 
 (defun notmuch-print-run-muttprint (&optional output)
-  "Pass the contents of the current buffer to 'muttprint'.
+  "Pass the contents of the current buffer to `muttprint'.
 
 Optional OUTPUT allows passing a list of flags to muttprint."
   (apply #'notmuch--call-process-region (point-min) (point-max)
diff --git a/emacs/notmuch-tag.el b/emacs/notmuch-tag.el
index 95977881..81101828 100644
--- a/emacs/notmuch-tag.el
+++ b/emacs/notmuch-tag.el
@@ -159,7 +159,7 @@ place of the tag.
 For example, to replace a tag with another string, simply use
 that string as a formatting expression.  To change the foreground
 of a tag to red, use the expression
-  (propertize tag 'face '(:foreground \"red\"))
+  (propertize tag \\='face \\='(:foreground \"red\"))
 
 See also `notmuch-tag-format-image', which can help replace tags
 with images."
@@ -191,7 +191,7 @@ By default this shows deleted tags with strike-through in red,
 unless strike-through is not available (e.g., emacs is running in
 a terminal) in which case it uses inverse video. To hide deleted
 tags completely set this to
-  '((\".*\" nil))
+  \\='((\".*\" nil))
 
 See `notmuch-tag-formats' for full documentation."
   :group 'notmuch-show
@@ -366,9 +366,9 @@ changed (the normal case) are shown using formats from
 (defcustom notmuch-before-tag-hook nil
   "Hooks that are run before tags of a message are modified.
 
-'tag-changes' will contain the tags that are about to be added or removed as
+`tag-changes' will contain the tags that are about to be added or removed as
 a list of strings of the form \"+TAG\" or \"-TAG\".
-'query' will be a string containing the search query that determines
+`query' will be a string containing the search query that determines
 the messages that are about to be tagged."
   :type 'hook
   :options '(notmuch-hl-line-mode)
@@ -377,9 +377,9 @@ the messages that are about to be tagged."
 (defcustom notmuch-after-tag-hook nil
   "Hooks that are run after tags of a message are modified.
 
-'tag-changes' will contain the tags that were added or removed as
+`tag-changes' will contain the tags that were added or removed as
 a list of strings of the form \"+TAG\" or \"-TAG\".
-'query' will be a string containing the search query that determines
+`query' will be a string containing the search query that determines
 the messages that were tagged."
   :type 'hook
   :options '(notmuch-hl-line-mode)
diff --git a/emacs/notmuch-wash.el b/emacs/notmuch-wash.el
index 653ecc2a..fd8a9d1e 100644
--- a/emacs/notmuch-wash.el
+++ b/emacs/notmuch-wash.el
@@ -381,7 +381,7 @@ original filename the sender had."
 	  (notmuch-wash-subject-to-filename subject 52)))
 
 (defun notmuch-wash-convert-inline-patch-to-part (msg depth)
-  "Convert an inline patch into a fake 'text/x-diff' attachment.
+  "Convert an inline patch into a fake `text/x-diff' attachment.
 
 Given that this function guesses whether a buffer includes a
 patch and then guesses the extent of the patch, there is scope
-- 
2.40.1

[PATCH 2/4] emacs: wrap docstrings

[David Bremner]

Suppress byte-compiler warnings about >80 character docstrings.
---
 emacs/notmuch-hello.el | 23 ++++++++++++++---------
 emacs/notmuch-show.el  | 19 ++++++++++++-------
 emacs/notmuch-tree.el  |  9 ++++++---
 3 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/emacs/notmuch-hello.el b/emacs/notmuch-hello.el
index 2d4fdc02..47ece536 100644
--- a/emacs/notmuch-hello.el
+++ b/emacs/notmuch-hello.el
@@ -717,7 +717,8 @@ with `notmuch-hello-query-counts'."
   "Keymap for \"notmuch hello\" buffers.")
 
 (define-derived-mode notmuch-hello-mode fundamental-mode "notmuch-hello"
-  "Major mode for convenient notmuch navigation. This is your entry portal into notmuch.
+  "Major mode for convenient notmuch navigation. This is your entry
+portal into notmuch.
 
 Saved searches are \"bookmarks\" for arbitrary queries. Hit RET
 or click on a saved search to view matching threads. Edit saved
@@ -853,7 +854,8 @@ Complete list of currently available key bindings:
 	(widget-create 'notmuch-search-item :value search :size width)))))
 
 (defun notmuch-hello-insert-searches (title query-list &rest options)
-  "Insert a section with TITLE showing a list of buttons made from QUERY-LIST.
+  "Insert a section with TITLE showing a list of buttons made from
+QUERY-LIST.
 
 QUERY-LIST should ideally be a plist but for backwards
 compatibility other forms are also accepted (see
@@ -867,13 +869,16 @@ Supports the following entries in OPTIONS as a plist:
 :show-empty-searches - show buttons with no matching messages
 :hide-if-empty - hide if no buttons would be shown
    (only makes sense without :show-empty-searches)
-:filter - This can be a function that takes the search query as its argument and
-   returns a filter to be used in conjunction with the query for that search or nil
-   to hide the element. This can also be a string that is used as a combined with
-   each query using \"and\".
-:filter-count - Separate filter to generate the count displayed each search. Accepts
-   the same values as :filter. If :filter and :filter-count are specified, this
-   will be used instead of :filter, not in conjunction with it."
+:filter - This can be a function that takes the search query as
+   its argument and returns a filter to be used in conjunction
+   with the query for that search or nil to hide the
+   element. This can also be a string that is used as a combined
+   with each query using \"and\".
+:filter-count - Separate filter to generate the count displayed
+   each search. Accepts the same values as :filter. If :filter
+   and :filter-count are specified, this will be used instead of
+   :filter, not in conjunction with it."
+
   (widget-insert title ": ")
   (when (and notmuch-hello-first-run (plist-get options :initially-hidden))
     (add-to-list 'notmuch-hello-hidden-sections title))
diff --git a/emacs/notmuch-show.el b/emacs/notmuch-show.el
index 4cc5aa57..4c0ad74d 100644
--- a/emacs/notmuch-show.el
+++ b/emacs/notmuch-show.el
@@ -2507,10 +2507,12 @@ kill-ring."
 (defun notmuch-show-stash-mlarchive-link (&optional mla)
   "Copy an ML Archive URI for the current message to the kill-ring.
 
-This presumes that the message is available at the selected Mailing List Archive.
+This presumes that the message is available at the selected
+Mailing List Archive.
 
-If optional argument MLA is non-nil, use the provided key instead of prompting
-the user (see `notmuch-show-stash-mlarchive-link-alist')."
+If optional argument MLA is non-nil, use the provided key instead
+of prompting the user (see
+`notmuch-show-stash-mlarchive-link-alist')."
   (interactive)
   (let ((url (cdr (assoc
 		   (or mla
@@ -2527,12 +2529,15 @@ the user (see `notmuch-show-stash-mlarchive-link-alist')."
        (concat url (notmuch-show-get-message-id t))))))
 
 (defun notmuch-show-stash-mlarchive-link-and-go (&optional mla)
-  "Copy an ML Archive URI for the current message to the kill-ring and visit it.
+  "Copy an ML Archive URI for the current message to the
+ kill-ring and visit it.
 
-This presumes that the message is available at the selected Mailing List Archive.
+This presumes that the message is available at the selected
+Mailing List Archive.
 
-If optional argument MLA is non-nil, use the provided key instead of prompting
-the user (see `notmuch-show-stash-mlarchive-link-alist')."
+If optional argument MLA is non-nil, use the provided key instead
+of prompting the user (see
+`notmuch-show-stash-mlarchive-link-alist')."
   (interactive)
   (notmuch-show-stash-mlarchive-link mla)
   (browse-url (current-kill 0 t)))
diff --git a/emacs/notmuch-tree.el b/emacs/notmuch-tree.el
index b58fa6a6..7fa403fc 100644
--- a/emacs/notmuch-tree.el
+++ b/emacs/notmuch-tree.el
@@ -200,7 +200,8 @@ Note that the author string should not contain whitespace
 
 (defface notmuch-tree-match-tree-face
   nil
-  "Face used in tree mode for the thread tree block graphics in messages matching the query."
+  "Face used in tree mode for the thread tree block graphics in
+messages matching the query."
   :group 'notmuch-tree
   :group 'notmuch-faces)
 
@@ -239,7 +240,8 @@ Note that the author string should not contain whitespace
 
 (defface notmuch-tree-no-match-tree-face
   nil
-  "Face used in tree mode for the thread tree block graphics in messages matching the query."
+  "Face used in tree mode for the thread tree block graphics in
+messages matching the query."
   :group 'notmuch-tree
   :group 'notmuch-faces)
 
@@ -1047,7 +1049,8 @@ message together with all its descendents."
     (notmuch-tree-insert-thread replies (1+ depth) tree-status)))
 
 (defun notmuch-tree-insert-thread (thread depth tree-status)
-  "Insert the collection of sibling sub-threads THREAD at depth DEPTH in the current forest."
+  "Insert the collection of sibling sub-threads THREAD at depth
+DEPTH in the current forest."
   (let ((n (length thread)))
     (cl-loop for tree in thread
 	     for count from 1 to n
-- 
2.40.1

[PATCH 3/4] emacs/address: rewrite docstring for n-a-selection-function

[David Bremner]

The previous version essentially repeated the source code, and
generated a compiler warning.
---
 emacs/notmuch-address.el | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/emacs/notmuch-address.el b/emacs/notmuch-address.el
index 1a4cdda2..f756254c 100644
--- a/emacs/notmuch-address.el
+++ b/emacs/notmuch-address.el
@@ -153,8 +153,7 @@ matching `notmuch-address-completion-headers-regexp'."
 ;;; Setup
 
 (defun notmuch-address-selection-function (prompt collection initial-input)
-  "Call (`completing-read'
-      PROMPT COLLECTION nil nil INITIAL-INPUT 'notmuch-address-history)"
+  "Default address selection function: delegate to completing read."
   (completing-read
    prompt collection nil nil initial-input 'notmuch-address-history))
 
-- 
2.40.1

[PATCH 4/4] emacs/mua: change name of ignored parameter

[David Bremner]

Suppress compiler warning.
---
 emacs/notmuch-mua.el | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/emacs/notmuch-mua.el b/emacs/notmuch-mua.el
index 3679d7d7..e4b7e9d1 100644
--- a/emacs/notmuch-mua.el
+++ b/emacs/notmuch-mua.el
@@ -403,7 +403,7 @@ instead of `message-mode' and SWITCH-FUNCTION is mandatory."
 
 (defun notmuch-mua-mail (&optional to subject other-headers _continue
 				   switch-function yank-action send-actions
-				   return-action &rest ignored)
+				   return-action &rest _ignored)
   "Invoke the notmuch mail composition window.
 
 The position of point when the function returns differs depending
-- 
2.40.1

Re: partial cleanup of warnings from byte compilation

[Tomi Ollila]

On Fri, Oct 06 2023, David Bremner wrote:

> This is almost all docstring formatting, except for the last
> patch.
>
> This is really just some low hanging fruit, but presumable eliminating
> some warnings is better than nothing. The warnings are more annoying
> now that native compilation exposes them to every user.
>

Series LGTM.

Tomi

Re: partial cleanup of warnings from byte compilation

[David Bremner]

Tomi Ollila <tomi.ollila@iki.fi> writes:

> On Fri, Oct 06 2023, David Bremner wrote:
>
>> This is almost all docstring formatting, except for the last
>> patch.
>>
>> This is really just some low hanging fruit, but presumable eliminating
>> some warnings is better than nothing. The warnings are more annoying
>> now that native compilation exposes them to every user.
>>
>
> Series LGTM.
>
> Tomi

Applied to master.

d