[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documentation for `seq-contains-p` is outdated
From: |
Daniel Martín |
Subject: |
Re: Documentation for `seq-contains-p` is outdated |
Date: |
Sat, 29 Aug 2020 20:18:56 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (darwin) |
Iwan in 't Groen <iwanintgroen@gmail.com> writes:
> Hi,
>
> When looking up the documentation for `seq-contains-p` it seems
> outdated.
>
> M-x elisp-index-search RET seq-contains-p RET returns:
>
> -- Function: seq-contains-p sequence elt &optional function
> This function returns non-‘nil’ if at least one element in SEQUENCE
> is equal to ELT. If the optional argument FUNCTION is non-‘nil’,
> it is a function of two arguments to use instead of the default
> ‘equal’.
>
> (seq-contains '(symbol1 symbol2) 'symbol1)
> ⇒ symbol1
> (seq-contains '(symbol1 symbol2) 'symbol3)
> ⇒ nil
>
> The title is correct but the information shown is for the obsolete
> `seq-contains` function.
Thank you for your contribution to Emacs. The change looks good to
me. If I'm not mistaken, this new function was introduced in 27.1, so
this might be a safe patch for 27.2. I've only left a comment, but let's
wait for other Emacs developers to do a proper review of this patch
(Nicolas Petton seems like the best person to do so).
>
> diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
> index 91c3049f87..bb80307c8c 100644
> --- a/doc/lispref/sequences.texi
> +++ b/doc/lispref/sequences.texi
> @@ -784,18 +784,18 @@ Sequence Functions
>
>
> @defun seq-contains-p sequence elt &optional function
> - This function returns non-@code{nil} if at least one element in
> + This function returns @code{t} if at least one element in
If we change this in the manual, I think we should also change the
documentation string for the function accordingly. I think that the
change makes sense, because seq-contains-p is a yes-or-no predicate and
"Return t if" complies with our tips for documentation strings.
> @var{sequence} is equal to @var{elt}. If the optional argument
> @var{function} is non-@code{nil}, it is a function of two arguments to
> use instead of the default @code{equal}.
>
> @example
> @group
> -(seq-contains '(symbol1 symbol2) 'symbol1)
> -@result{} symbol1
> +(seq-contains-p '(symbol1 symbol2) 'symbol1)
> +@result{} t
> @end group
> @group
> -(seq-contains '(symbol1 symbol2) 'symbol3)
> +(seq-contains-p '(symbol1 symbol2) 'symbol3)
> @result{} nil
> @end group
> @end example