Re: Documentation for `seq-contains-p` is outdated

["Daniel Martín" <mardani29@yahoo.es>]

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