bug#12628: 24.2.50; doc of `easy-menu-define'

bug#12628: 24.2.50; doc of `easy-menu-define'

[Drew Adams]

This doc is all the more important because the doc for nearly all of the
other `easy-menu-*' functions just punts and points back to this doc.
It needs to be clear, complete, and correct.
 
In practice, users have to read the source code and work their way
through low-level helper function `easy-menu-convert-item-1' to figure
out what a menu item really can be.  Not good.
 
1. AFAICT, there is nothing in the doc string that corresponds to use
cases like these, for MENU:
 
["--" t]
["--" nil nil]
 
The doc says that CALLBACK is a command or a _list_ to evaluate.
`t' is certainly not a list.
 
The doc also does not say anything about what CALLBACK is evaluated for,
so presumably it is only for its side effects and its value is not used
(?).  This should be made explicit - e.g., "CALLBACK is an expression
that is evaluated for its side effects."
 
2. What on earth is ARG here?  It needs to be described.
 
 "Alternatively, a menu item may have the form:
   [ NAME CALLBACK [ KEYWORD ARG ] ... ]"
 
3. Why isn't there anything about `easy-menu*' in the Elisp manual?  The
manual covers defining and modifying menus, but it doesn't cover the
standard "easy" way to do that defined by RMS.

In GNU Emacs 24.2.50.1 (i386-mingw-nt5.1.2600)
 of 2012-10-09 on DANI-PC
Bzr revision: 110489 monnier@iro.umontreal.ca-20121009163751-ui2zwwoaj8bqwj52
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libxpm-3.5.8/include -I../../libs/libxpm-3.5.8/src
 -I../../libs/libpng-1.4.10 -I../../libs/zlib-1.2.6
 -I../../libs/giflib-4.1.4-1/include -I../../libs/jpeg-6b-4/include
 -I../../libs/tiff-3.8.2-1/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.16/include
 -I../../libs/libiconv-1.14-2-mingw32-dev/include'
 

bug#12628: 24.2.50; doc of `easy-menu-define'

[Chong Yidong]

"Drew Adams" <drew.adams@oracle.com> writes:

> 1. AFAICT, there is nothing in the doc string that corresponds to use
> cases like these, for MENU:
>  
> 2. What on earth is ARG here?  It needs to be described.
>  
> 3. Why isn't there anything about `easy-menu*' in the Elisp manual?  The
> manual covers defining and modifying menus, but it doesn't cover the
> standard "easy" way to do that defined by RMS.

Fixed in trunk.