bug#60470: 26.3; Doc string of `recentf-keep'

[Drew Adams <drew.adams@oracle.com>]

> > Please consider saying in the doc string what it 
> > means to "keep" a file name in the recent list.
> >
> > The doc string goes into what it means to be a
> > predicate, but it says nothing, really, about
> > what this option means/does, because it tells
> > you nothing about what "keeping" amounts to.
> 
> I've rad the doc string, and I see nothing wrong with it.  In
> particular, I did find there the explanation of what "keeping" means.
> 
> So I'm closing this bug.

FWIW, I don't see any such explanation, in any doc string.

Following the code - e.g. the places where `recentf-keep-p'
is used, I can see that the use of `recentf-keep' differs
from the use of `recentf-exclude' (besides filtering in
instead of out) in that `recentf-keep' filtering happens
when you kill a buffer (via `recentf-track-closed-file')
or whether "cleanup" occurs.  That info is missing from
the option doc string.

Other than searching thus in the code, I see no way for a
user to know what "keep" means.  Does it refer to keeping
persistently, i.e., not removing when saving?  Does it
refer to keeping after the buffer for the file is killed?
When a "cleanup" occurs?  "Keep" in what way, wrt what?

I think a user will wonder about this.  And in particular
I don't see anything in the doc string of `recentf-keep'
that speaks to it - nothing that makes you not wonder how
this differs from the use of option `recentf-exclude'
(besides filtering in the opposite sense).

We give users two options for filtering the recentf list.
The doc string of one seems clear enough: it prevents
some file names _from being added_ to the list.  The
other doc string doesn't speak to the presumed _removal_
operations for which it prevents removal.  Its predicates
and regexps prevent removal of certain files - but what
is it that would otherwise cause their removal?

You can figure it out by either (1) looking at the code
or (2) checking _all_ of the doc to get a list of the
possible removal events/operations/occurrences, and
surmising that `recentf-keep' takes effect for all of
them.  But I don't see how you can figure it out just
by looking at the `recentf-keep' doc string.

Would you mind pointing to the part of the doc string
that you think explains what "keeping" means?  I really
don't see it.