bug#19371: 25.0.50; doc of functions and macros defined in macroexp.el

[Drew Adams]

1. `macroexp-let2' is used plenty in the Lisp sources now.  And its
documentation is in complete/rudimentary.  Please fix this.

1a. It is not even mentioned in the Elisp manual.  Please document it 
properly there.

1b. The doc string says:

 "Bind VAR to a copyable expression that returns the value of EXP.
  This is like `(let ((v ,EXP)) ,EXPS) except that `v' is a new
  generated symbol which EXPS can find in VAR."

What on Earth does it mean for EXPS to find the symbol `v' in VAR?
VAR is a symbol.  What does it mean for a list of expressions to find
another symbol "in" symbol VAR?  Just what does it mean for the
expression to which VAR is bound to be "copyable" or not "copyable"?
If you mean `macroexp-copyable-p' then say so.

I'm only presuming that EXPS is a list of Lisp sexps.  It is not even
described, but it needs to be.  Nor is EXP described, for that matter.
I'm guessing that it is a Lisp sexp, but it too needs to be specified
properly.

What does it mean for "the `let'" to be skipped"?  How is TEST really
used - what is it for?

So far, this macro description is gobbledygook.  Please document the
macro properly.

2. And then there is `macroexp-let2*', whose doc string says only to
bind each binding (bind a binding?!) "as `macrolet2' does".  That
means nothing.  Presumably, based on the `*' in the name, the behavior
is similar to that of `let*'.  If so, you can use the doc of `let*
as inspiration.

3. The doc strings of `macroexp-let*', `macroexp-progn', and others
say that the function returns "an expression equivalent to" some
expression.  They should say what they mean by equivalence, here.
If you mean that they use `macroexp-quote' to create the
"equivalent" expression then say so.

The doc string of `macroexp-let*' needs to use BINDINGS and EXP, not
the same in lowercase, in the equivalent expression.  Similarly, the
doc string of `macroexp-if' needs to use uppercase TEST, THEN, and
ELSE.

4. The doc string of `macroexp--accumulate' refers to parameters
that do not exist: VAR and LIST.  It should say explicitly (and
not just via `(fn ...)') that the first parameter is a list of
the form `(VAR LIST)'.  (And no, it does not matter that this
macro is internal.)

5. The doc string of `macroexp--cons' is incomprehensible.


In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-11-30 on LEG570
Bzr revision: 3517da701ea5d16c296745d6678988b06bee615d
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --without-dbus --enable-checking=yes,glyphs
 CPPFLAGS=-DGLYPH_DEBUG=1'