bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated

bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated

[Iwan in 't Groen]

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.


In GNU Emacs 28.0.50 (build 1, x86_64-apple-darwin19.6.0, NS appkit-1894.60 Version 10.15.6 (Build 19G73))
 of 2020-08-15 built on Iwans-MacBook-Air.local
Repository revision: 5b463af8dda4d66bb63a7ce58177e83a42541bac
Repository branch: master
System Description:  Mac OS X 10.15.6

Recent messages:
For information about GNU Emacs and the GNU system, type C-h C-a.
Found ‘seq-contains-p’ in Index.  (Only match)

Configured features:
NOTIFY KQUEUE ACL GNUTLS LIBXML2 ZLIB TOOLKIT_SCROLL_BARS NS MODULES
THREADS PDUMPER

Important settings:
  value of $LC_ALL: en_US.UTF-8
  value of $LC_CTYPE: UTF-8
  value of $LANG: en_US.UTF-8
  locale-coding-system: utf-8-unix

Major mode: Info

Minor modes in effect:
  tooltip-mode: t
  global-eldoc-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  tool-bar-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  buffer-read-only: t
  line-number-mode: t
  transient-mark-mode: t

Load-path shadows:
None found.

Features:
(shadow sort mail-extr emacsbug message rmc puny dired dired-loaddefs
rfc822 mml mml-sec password-cache epa derived epg epg-config gnus-util
rmail rmail-loaddefs text-property-search time-date subr-x seq mm-decode
mm-bodies mm-encode mail-parse rfc2231 mailabbrev gmm-utils mailheader
cl-loaddefs cl-lib sendmail rfc2047 rfc2045 ietf-drums mm-util
mail-prsvr mail-utils info easymenu thingatpt term/xterm xterm byte-opt
gv bytecomp byte-compile cconv tooltip eldoc electric uniquify
ediff-hook vc-hooks lisp-float-type mwheel term/ns-win ns-win
ucs-normalize mule-util term/common-win tool-bar dnd fontset image
regexp-opt fringe tabulated-list replace newcomment text-mode elisp-mode
lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow isearch
timer select scroll-bar mouse jit-lock font-lock syntax facemenu
font-core term/tty-colors frame minibuffer cl-generic cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese eucjp-ms cp51932 hebrew greek romanian slovak czech european
ethiopic indian cyrillic chinese composite charscript charprop
case-table epa-hook jka-cmpr-hook help simple abbrev obarray
cl-preloaded nadvice loaddefs button faces cus-face macroexp files
text-properties overlay sha1 md5 base64 format env code-pages mule
custom widget hashtable-print-readable backquote threads kqueue cocoa ns
multi-tty make-network-process emacs)

Memory information:
((conses 16 116389 7554)
 (symbols 48 6344 1)
 (strings 32 21018 1550)
 (string-bytes 1 602251)
 (vectors 16 8385)
 (vector-slots 8 107118 7376)
 (floats 8 27 31)
 (intervals 56 16372 42)
 (buffers 992 12))

bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated

[Eli Zaretskii]

> From: Iwan in 't Groen <iwanintgroen@gmail.com>
> Date: Sat, 15 Aug 2020 16:04:12 +0200
> 
>          (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.

Thanks, fixed.

bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated

[Iwan in 't Groen]

> On 15 Aug 2020, at 17:17, Eli Zaretskii <eliz@gnu.org> wrote:
> 
>> From: Iwan in 't Groen <iwanintgroen@gmail.com>
>> Date: Sat, 15 Aug 2020 16:04:12 +0200
>> 
>>         (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.
> 
> Thanks, fixed.

The return value in the description of this function (now a predicate) should also be changed.

Currently is says:
This function returns non-‘nil’ if at least one element in SEQUENCE is equal to ELT.

It should be:
This function returns ’t’ if at least one element in SEQUENCE is equal to ELT.

diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
index ca52369bd0..bb80307c8c 100644
--- a/doc/lispref/sequences.texi
+++ b/doc/lispref/sequences.texi
@@ -784,7 +784,7 @@ 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}.

bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated

[Basil L. Contovounesios]

Iwan in 't Groen <iwanintgroen@gmail.com> writes:

> The return value in the description of this function (now a predicate) should also be changed.
>
> Currently is says:
> This function returns non-‘nil’ if at least one element in SEQUENCE is equal to ELT.
>
> It should be:
> This function returns ’t’ if at least one element in SEQUENCE is equal to ELT.
>
> diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi
> index ca52369bd0..bb80307c8c 100644
> --- a/doc/lispref/sequences.texi
> +++ b/doc/lispref/sequences.texi
> @@ -784,7 +784,7 @@ 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}.

I don't feel strongly about this, but note that in general it's common
and fine to say non-nil in place of t, even when the value is t.
Predicates are allowed to return other non-nil values too, see
e.g. proper-list-p.  The only time the distinction matters enough to
document it is when different non-nil values have different meanings,
e.g. with while-no-input or with certain user options.

HTH,

-- 
Basil

bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated

[Eli Zaretskii]

> From: Iwan in 't Groen <iwanintgroen@gmail.com>
> Date: Wed, 19 Aug 2020 10:14:28 +0200
> Cc: 42871-done@debbugs.gnu.org
> 
> The return value in the description of this function (now a predicate) should also be changed.
> 
> Currently is says:
> This function returns non-‘nil’ if at least one element in SEQUENCE is equal to ELT.
> 
> It should be:
> This function returns ’t’ if at least one element in SEQUENCE is equal to ELT.

I don't see why we need to change the text: 't' is definitely non-nil,
right?