bug#32016: 27.0; (elisp) `Imenu'

bug#32016: 27.0; (elisp) `Imenu'

[Drew Adams]

The description of `imenu-generic-expression' is incomplete.  It does
not specify the case where argument REGEXP is a function.

The doc string describes this use case this way:

REGEXP may also be a function, called without arguments.  It is expected
to search backwards.  It must return true and set 'match-data' if it
finds another element.

Unfortunately, the last sentence there is unclear.  The function does
not "find another element".  It finds a definition construct in the
buffer, and it sets match data for it.  It does not construct or "find"
an element of the list that is the variable value.

But this bug report is about the missing description of the
REGEXP-as-function case.

In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32)
 of 2018-03-21
Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install -C 'CFLAGS=-O2 -static -g3''

bug#32016: 27.0; (elisp) `Imenu'

[Eli Zaretskii]

> Date: Fri, 29 Jun 2018 23:42:02 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> The description of `imenu-generic-expression' is incomplete.  It does
> not specify the case where argument REGEXP is a function.
> 
> The doc string describes this use case this way:
> 
> REGEXP may also be a function, called without arguments.  It is expected
> to search backwards.  It must return true and set 'match-data' if it
> finds another element.
> 
> Unfortunately, the last sentence there is unclear.  The function does
> not "find another element".  It finds a definition construct in the
> buffer, and it sets match data for it.  It does not construct or "find"
> an element of the list that is the variable value.

Thanks, I fixed the doc string.

> But this bug report is about the missing description of the
> REGEXP-as-function case.

What is this about?  A left-over of editing some other message?

bug#32016: 27.0; (elisp) `Imenu'

[Drew Adams]

> > The description of `imenu-generic-expression' is incomplete.  It does
> > not specify the case where argument REGEXP is a function...
>
> Thanks, I fixed the doc string.

Thanks.

> > But this bug report is about the missing description of the
> > REGEXP-as-function case.
> 
> What is this about?  A left-over of editing some other message?

No; it refers to the introductory sentences (quoted above)
and the description of the bug, which is about the doc not
specifying the case where REGEXP is a function.

It appears after an aside mention that the sentence about 
the unclear sentence about "find another element".  I didn't
want the bug about missing spec of REGEXP as a function to
be side-tracked by the parenthetical mention of some unclear
text that is not related to that.