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.


In GNU Emacs 22.0.50.1 (i386-mingw-nt5.1.2600)
 of 2006-03-20 on W2ONE
X server distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4) --cflags -Id:/g/include'

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: ENU
  locale-coding-system: cp1252
  default-enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  encoded-kbd-mode: t
  tooltip-mode: t
  auto-compression-mode: t
  tool-bar-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  unify-8859-on-encoding-mode: t
  utf-translate-cjk-mode: t
  line-number-mode: t
  transient-mark-mode: identity

Recent input:
<down-mouse-1> <mouse-1> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down> <down> <down> <down> <down> <down> <down> 
<down> <down-mouse-1> <mouse-1> <double-down-mouse-1> 
<double-mouse-1> <down-mouse-1> <mouse-1> <wheel-down> 
<double-wheel-down> <wheel-up> <wheel-up> <wheel-up> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<menu-bar> <help-menu> <report-emacs-bug> C-g C-g <down-mouse-1> 
<mouse-1> <wheel-up> <double-wheel-up> <triple-wheel-up> 
<wheel-up> <double-wheel-up> <wheel-up> <double-wheel-up> 
<wheel-up> <double-wheel-up> <triple-wheel-up> <wheel-up> 
<down-mouse-1> <mouse-1> C-h f <return> <switch-frame> 
<switch-frame> <down-mouse-1> <mouse-1> <help-echo> 
<help-echo> <help-echo> <help-echo> <help-echo> <help-echo> 
<help-echo> <menu-bar> <help-menu> <report-emacs-b
ug>

Recent messages:
Loading pp...done
Type C-x 1 to remove help window.  
You didn't specify a function
Quit [2 times]
Loading imenu...done
mwheel-scroll: Beginning of buffer
Loading easymenu...done
Mark saved where search started [3 times]
Loading emacsbug...done
Quit [2 times]