Documentation for `seq-contains-p` is outdated

Documentation for `seq-contains-p` is outdated

[Iwan in 't Groen]

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.

Best regards,
Iwan in ’t Groen

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
 @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

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

[Daniel Martín]

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

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

[Eli Zaretskii]

> From: Daniel Martín <mardani29@yahoo.es>
> Cc: emacs-devel@gnu.org
> Date: Sat, 29 Aug 2020 20:18:56 +0200
> 
> 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).

This was already fixed, see bug#42871.