GNU bug report logs - #64367
28.2; doc string of `text-property-search-forward'

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 64367 in the body.
You can then email your comments to 64367 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: Drew Adams <drew.adams <at> oracle.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: 28.2; doc string of `text-property-search-forward'
Date: Fri, 30 Jun 2023 15:07:02 +0000

The signature is this:

(text-property-search-forward PROPERTY
   &optional VALUE PREDICATE NOT-CURRENT)

The arguments should be described in order.

But the first line of the doc string - the most important - says this:

 Search for the next region of text where PREDICATE is true.

Not only is PREDICATE optional; it is not even the first optional arg.
The first line should describe the _default_ behavior (nil VALUE, nil
PREDICATE).  Something like this:

 Search forward for text where PROPERTY is non-nil.

Then go on to introduce, first VALUE, then PREDICATE, then NOT-CURRENT.

In GNU Emacs 28.2 (build 2, x86_64-w64-mingw32)
 of 2022-09-13
Windowing system distributor `Microsoft Corp.', version 10.0.19045
Configured using:
 `configure --with-modules --without-dbus --with-native-compilation
 --without-compress-install CFLAGS=-O2'

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 64367-done <at> debbugs.gnu.org
Subject: Re: bug#64367: 28.2; doc string of `text-property-search-forward'
Date: Sat, 01 Jul 2023 12:32:41 +0300

> From: Drew Adams <drew.adams <at> oracle.com>
> Date: Fri, 30 Jun 2023 15:07:02 +0000
> 
> The signature is this:
> 
> (text-property-search-forward PROPERTY
>    &optional VALUE PREDICATE NOT-CURRENT)
> 
> The arguments should be described in order.

Only preferably so.  It is not always possible to do so, and thus it
is not a hard requirement.

In this case, I see no way of describing the arguments in order and
still producing a useful doc string, let alone its first line.

> But the first line of the doc string - the most important - says this:
> 
>  Search for the next region of text where PREDICATE is true.
> 
> Not only is PREDICATE optional; it is not even the first optional arg.
> The first line should describe the _default_ behavior (nil VALUE, nil
> PREDICATE).

Now fixed on the emacs-29 branch.

> Something like this:
> 
>  Search forward for text where PROPERTY is non-nil.

This loses information and is also inaccurate, so I used a different
text:

  Search for next region of text where PREDICATE returns non-nil for PROPERTY.

Closing.

Previous Next

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