bug#22192: Doc string of macroexp-let2 is obscure.

[Nicolas Richard]

Alan Mackenzie <acm@muc.de> writes:
>     "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.
>     TEST should be the name of a predicate on EXP checking whether the `let' 
> can
>     be skipped; if nil, as is usual, `macroexp-const-p' is used."
>
> This macro is widely used (over 50 times) in Emacs, and is not
> documented in the Elisp manual.  The doc string is difficult to
> understand.

I agree that the docstring was pretty obscure, but it was modified
in commit 5e3fde03b45877d3e30f859a14c10043e637aa63 

It now is :
    Evaluate BODY with SYM bound to an expression for EXP’s value.
    The intended usage is that BODY generates an expression that
    will refer to EXP’s value multiple times, but will evaluate
    EXP only once.  As BODY generates that expression, it should
    use SYM to stand for the value of EXP.

    If EXP is a simple, safe expression, then SYM’s value is EXP itself.
    Otherwise, SYM’s value is a symbol which holds the value produced by
    evaluating EXP.  The return value incorporates the value of BODY, plus
    additional code to evaluate EXP once and save the result so SYM can
    refer to it.

    If BODY consists of multiple forms, they are all evaluated
    but only the last one’s value matters.

    TEST is a predicate to determine whether EXP qualifies as simple and
    safe; if TEST is nil, only constant expressions qualify.

    Example:
     (macroexp-let2 nil foo EXP
       `(* ,foo ,foo))
    generates an expression that evaluates EXP once,
    then returns the square of that value.
    You could do this with
      (let ((foovar EXP))
        (* foovar foovar))
    but using ‘macroexp-let2’ produces more efficient code in
    cases where EXP is a constant.

-- 
Nicolas