RE: Doc strings of imenu--generic-function and imenu-generic-expression incomplete

[Drew Adams]

    imenu--generic-function is only called with argument
    imenu-generic-expression, so describing its argument indirectly
    describes imenu-generic-expression.  That is what the doc string of
    imenu--generic-function does. The doc string of
    imenu-generic-expression does not describe it; it simply refers to the
    doc string of imenu--generic-function. First, this is backwards: the
    structure of the variable value should be described in the variable's
    doc string.

    More importantly -

    This structure description (in the doc string of
    imenu--generic-function) says that one of the forms the value can take
    is this: (MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...).

    However, the only description of FUNCTION and ARGUMENTS is that they
    are copied from imenu-generic-expression! In other words, there is no
    explanation (anywhere) of what they are. Something needs to be
    communicated about what the FUNCTION is for (we can guess that it is a
    function) and what the ARGUMENTS are for - that is, how they are used
    and what reasonable and unreasonable values for them might be.

I should have added that the doc string of imenu--generic-function also says
this about (MENU-TITLE REGEXP INDEX FUNCTION ARGUMENTS...): it
"creates a special element of the form (NAME POSITION-MARKER FUNCTION
ARGUMENTS...)". There is no explanation anywhere of either NAME or
POSITION-MARKER or of what such a "special element" is or is for.

Similarly, at the end of the doc string is this:

"Returns an index of the current buffer as an alist.  The elements in
the alist look like:
 (INDEX-NAME . INDEX-POSITION)
or like:
 (INDEX-NAME INDEX-POSITION FUNCTION ARGUMENTS...)
They may also be nested index alists like:
 (INDEX-NAME . INDEX-ALIST)
depending on patterns."

This introduces two new names that are, once again, not explained:
INDEX-NAME and INDEX-POSITION.

In sum, these two doc strings need some rework. What they are trying to say
seems unclear and incomplete.