bug#36850: 26.2; Customizing nnmail-expiry-wait-function doesn't work

[Basil L. Contovounesios]

reassign 36850 emacs,gnus
severity 36850 minor
tags 36850 + patch
quit

Allen Li <darkfeline@felesatra.moe> writes:

> Attempting to customize nnmail-expiry-wait-function and selecting a
> custom function results in the error:
>
> read: Symbol’s function definition is void: nnmail-

Indeed, I don't understand why its custom :type was written that way.

While looking at this, I noticed some room for clarification in the
relevant docs.  Are the following clarifications welcome and suitable
for emacs-26?

>From d0a0d10fff7e1310be63cc832ea6bcc7a0ff6784 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Fri, 2 Aug 2019 15:54:09 +0300
Subject: [PATCH] Fix nnmail-expiry-wait docs and custom :types

* doc/misc/gnus.texi (Group Parameters, Expiring Mail):
* lisp/gnus/gnus-cus.el (gnus-group-parameters): Clarify
descriptions of nnmail-expiry, nnmail-expiry-wait, and
nnmail-expiry-wait-function.
* lisp/gnus/nnmail.el (nnmail-expiry-wait)
(nnmail-expiry-wait-function): Clarify docstrings and fix custom
:types (bug#36850).
---
 doc/misc/gnus.texi    | 50 ++++++++++++++++++++++++-------------------
 lisp/gnus/gnus-cus.el |  8 +++----
 lisp/gnus/nnmail.el   | 35 +++++++++++++++---------------
 3 files changed, 50 insertions(+), 43 deletions(-)

diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index dcba47aca0..32d98abd7e 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -2916,9 +2916,9 @@ Group Parameters
 If the group parameter has an element that looks like
 @code{(expiry-wait . 10)}, this value will override any
 @code{nnmail-expiry-wait} and @code{nnmail-expiry-wait-function}
-(@pxref{Expiring Mail}) when expiring expirable messages.  The value
-can either be a number of days (not necessarily an integer) or the
-symbols @code{never} or @code{immediate}.
+settings (@pxref{Expiring Mail}) when expiring expirable messages.
+The value can be either a number of days (not necessarily an integer),
+or one of the symbols @code{never} or @code{immediate}.
 
 @item expiry-target
 @cindex expiry-target
@@ -15878,40 +15878,46 @@ Expiring Mail
 
 @vindex nnmail-expiry-wait
 The @code{nnmail-expiry-wait} variable supplies the default time an
-expirable article has to live.  Gnus starts counting days from when the
-message @emph{arrived}, not from when it was sent.  The default is seven
-days.
+expirable article has to live.  The value of this variable can be
+either a number of days (not necessarily an integer), or one of the
+symbols @code{immediate} or @code{never}, meaning an article is
+immediately or never expirable, respectively.
 
-Gnus also supplies a function that lets you fine-tune how long articles
-are to live, based on what group they are in.  Let's say you want to
-have one month expiry period in the @samp{mail.private} group, a one day
-expiry period in the @samp{mail.junk} group, and a six day expiry period
-everywhere else:
+Gnus starts counting days from when the message @emph{arrived}, not
+from when it was sent.  The default is seven days.
 
 @vindex nnmail-expiry-wait-function
+The @code{nnmail-expiry-wait-function} variable lets you fine-tune how
+long articles are to live, based on what group they are in.  When set
+to a function, its returned value, if non-@code{nil}, overrides that
+of @code{nnmail-expiry-wait}.  Otherwise, the value of
+@code{nnmail-expiry-wait} is used instead.
+
+For example, let's say you want to have a one month expiry period in
+the @samp{mail.private} group, a one day expiry period in the
+@samp{mail.junk} group, and a six day expiry period everywhere else.
+This can be achieved as follows:
+
 @lisp
 (setq nnmail-expiry-wait-function
       (lambda (group)
-       (cond ((string= group "mail.private")
+        (cond ((string= group "mail.private")
                31)
-             ((string= group "mail.junk")
+              ((string= group "mail.junk")
                1)
-             ((string= group "important")
+              ((string= group "important")
                'never)
-             (t
+              (t
                6))))
 @end lisp
 
 The group names this function is fed are ``unadorned'' group
 names---no @samp{nnml:} prefixes and the like.
 
-The @code{nnmail-expiry-wait} variable and
-@code{nnmail-expiry-wait-function} function can either be a number (not
-necessarily an integer) or one of the symbols @code{immediate} or
-@code{never}.
-
-You can also use the @code{expiry-wait} group parameter to selectively
-change the expiry period (@pxref{Group Parameters}).
+As an alternative to the variables @code{nnmail-expiry-wait} or
+@code{nnmail-expiry-wait-function}, you can also use the
+@code{expiry-wait} group parameter to selectively change the expiry
+period (@pxref{Group Parameters}).
 
 @vindex nnmail-expiry-target
 The normal action taken when expiring articles is to delete them.
diff --git a/lisp/gnus/gnus-cus.el b/lisp/gnus/gnus-cus.el
index fb8b300e35..574b0c6913 100644
--- a/lisp/gnus/gnus-cus.el
+++ b/lisp/gnus/gnus-cus.el
@@ -140,10 +140,10 @@ gnus-group-parameters
                                 :format "%v")) "\
 When to expire.
 
-Overrides any `nnmail-expiry-wait' and `nnmail-expiry-wait-function'
-when expiring expirable messages.  The value can either be a number of
-days (not necessarily an integer) or the symbols `never' or
-`immediate'.")
+Overrides any `nnmail-expiry-wait' or `nnmail-expiry-wait-function'
+settings when expiring expirable messages.  The value can be
+either a number of days (not necessarily an integer), or one of
+the symbols `never' or `immediate'.")
 
     (expiry-target (choice :tag "Expiry Target"
                           :value delete
diff --git a/lisp/gnus/nnmail.el b/lisp/gnus/nnmail.el
index 0699e81812..f8248b0190 100644
--- a/lisp/gnus/nnmail.el
+++ b/lisp/gnus/nnmail.el
@@ -157,32 +157,33 @@ nnmail-default-file-modes
 
 (defcustom nnmail-expiry-wait 7
   "Expirable articles that are older than this will be expired.
-This variable can either be a number (which will be interpreted as a
-number of days) -- this doesn't have to be an integer.  This variable
-can also be `immediate' and `never'."
+This variable can be either a number of days (not necessarily an
+integer), or one of the symbols `immediate' or `never', meaning
+an article is immediately or never expirable, respectively.
+For more granular control, see `nnmail-expiry-wait-function'."
   :group 'nnmail-expire
-  :type '(choice (const immediate)
-                (number :tag "days")
-                (const never)))
+  :type '(choice (const :tag "Immediate" immediate)
+                 (const :tag "Never" never)
+                 (number :tag "Days")))
 
 (defcustom nnmail-expiry-wait-function nil
-  "Variable that holds function to specify how old articles should be before 
they are expired.
-The function will be called with the name of the group that the expiry
-is to be performed in, and it should return an integer that says how
-many days an article can be stored before it is considered \"old\".
-It can also return the values `never' and `immediate'.
+  "Function to determine how old articles should be before they are expired.
+The function is called with the name of the group that the expiry
+is to be performed in, and should return a value supported by
+`nnmail-expiry-wait', which it overrides.  If this variable is
+nil, the value of `nnmail-expiry-wait' is used instead.
 
 E.g.:
 
 \(setq nnmail-expiry-wait-function
-      (lambda (newsgroup)
-       (cond ((string-match \"private\" newsgroup) 31)
-             ((string-match \"junk\" newsgroup) 1)
-             ((string-match \"important\" newsgroup) \\='never)
-             (t 7))))"
+      (lambda (group)
+        (cond ((string-match-p \"private\" group) 31)
+              ((string-match-p \"junk\" group) 1)
+              ((string-match-p \"important\" group) \\='never)
+              (t 7))))"
   :group 'nnmail-expire
   :type '(choice (const :tag "nnmail-expiry-wait" nil)
-                (function :format "%v" nnmail-)))
+                 (function :tag "Custom function")))
 
 (defcustom nnmail-expiry-target 'delete
   "Variable that says where expired messages should end up.
-- 
2.20.1

Thanks,

-- 
Basil