bug#8285: 24.0.50; doc of `imenu-generic-expression' and `imenu--generic-function'

[Drew Adams]

> > If you don't understand the problem, change these names to UU, VV,
> > WW, XX, YY, and ZZ, and see if you understand the doc.
> 
> This argument is bogus: names of symbols can and should bear
> significant semantic information that helps to understand their roles,
> and if that information is descriptive enough, there's no need for any
> further definitions.

This doc is bogus.  Using good names helps - always.  It is typically not
sufficient, including in this case.

> As an extreme example, consider:
>  (defun call-func (function &rest arguments)
>    "Call FUNCTION with ARGUMENTS."

Sorry, not interested in your "extreme example".  Speak to the specific case
reported, please.  The meanings of the names I cited are _not_ self-evident.

> I see no need to explain the arguments in this example.

Which example?  Yours?  Agreed.  But irrelevant.
Or the example reported in this bug report?

This report is not immediately about explaining the argument to
`imenu--generic-function'.  That argument, PATTERNS, _is_ described.

But it is described in terms of undefined terms, so it is not described well
enough.  It is the explanations of those terms that are missing, not a
description of the argument, PATTERNS.

> I'm not saying that the doc string in question could not use some
> improvement.  But since imenu is about creating indices of functions
> in a program source file,

Oh no it is NOT.  Imenu is used for indexing _lots_ of things besides just
functions: variables, types, keys,...  Nearly anything you want, in fact.

> at least FUNCTION and ARGUMENTS do not need
> any further explanations, IMO.

If their meanings are obvious to you then surely you can explain what they are.
Please add the explanation to the doc string so the rest of us can understand.

What are they?  Sure, from their names one can understand that they refer to
some function and some arguments (maybe even arguments to function FUNCTION),
respectively.  But which function?  Which arguments to which function?

What's more (forgot to mention), we see this: "with FUNCTION and ARGUMENTS
copied from PATTERNS" as the explanation (!) of these two terms.  PATTERNS is
the argument to `imenu--generic-function'.

But how are FUNCTION and ARGUMENTS "copied" from PATTERNS?  What does that even
mean?  The doc already describes the elements of alist PATTERNS, and FUNCTION
and ARGUMENTS occur inside one type of element.  How are they "copied" from
PATTERNS?

None of the terms I mentioned are explained.  The meanings of none of them are
clear based only on their names.