GNU bug report logs - #42871
28.0.50; Documentation for `seq-contains-p` is outdated

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 42871 in the body.
You can then email your comments to 42871 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Iwan in 't Groen <iwanintgroen <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.0.50; Documentation for `seq-contains-p` is outdated
Date: Sat, 15 Aug 2020 16:04:12 +0200

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

Message #10 received at 42871-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Iwan in 't Groen <iwanintgroen <at> gmail.com>
Cc: 42871-done <at> debbugs.gnu.org
Subject: Re: bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated
Date: Sat, 15 Aug 2020 18:17:38 +0300

> From: Iwan in 't Groen <iwanintgroen <at> 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.

Message #13 received at 42871-done <at> debbugs.gnu.org (full text, mbox):

From: Iwan in 't Groen <iwanintgroen <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 42871-done <at> debbugs.gnu.org
Subject: Re: bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated
Date: Wed, 19 Aug 2020 10:14:28 +0200

> On 15 Aug 2020, at 17:17, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
>> From: Iwan in 't Groen <iwanintgroen <at> 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}.

Message #16 received at 42871 <at> debbugs.gnu.org (full text, mbox):

From: "Basil L. Contovounesios" <contovob <at> tcd.ie>
To: Iwan in 't Groen <iwanintgroen <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 42871 <at> debbugs.gnu.org
Subject: Re: bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated
Date: Wed, 19 Aug 2020 11:56:45 +0100

Iwan in 't Groen <iwanintgroen <at> 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

Message #19 received at 42871 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Iwan in 't Groen <iwanintgroen <at> gmail.com>
Cc: 42871 <at> debbugs.gnu.org
Subject: Re: bug#42871: 28.0.50; Documentation for `seq-contains-p` is outdated
Date: Wed, 19 Aug 2020 17:35:28 +0300

> From: Iwan in 't Groen <iwanintgroen <at> gmail.com>
> Date: Wed, 19 Aug 2020 10:14:28 +0200
> Cc: 42871-done <at> 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?

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.