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).

3 files changed, 50 insertions, 43 deletions

diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi
index f0458847295..9c3ec41462d 100644
--- a/doc/misc/gnus.texi
+++ b/doc/misc/gnus.texi
@@ -2917,9 +2917,9 @@ See also @code{gnus-total-expirable-newsgroups}.
 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
@@ -15826,40 +15826,46 @@ don't really mix very well.
 
 @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 66fa3e0590f..80459a7d62c 100644
--- a/lisp/gnus/gnus-cus.el
+++ b/lisp/gnus/gnus-cus.el
@@ -140,10 +140,10 @@ rules as described later).")
 				 :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 c52bc03e109..0f560d300f9 100644
--- a/lisp/gnus/nnmail.el
+++ b/lisp/gnus/nnmail.el
@@ -159,32 +159,33 @@ If nil, groups like \"mail.misc\" will end up in directories like
 
 (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.