Re: master 2e9111813b: Add two classic Common Lisp macro-writing macros

[Eli Zaretskii]

> From: Sean Whitton <spwhitton@spwhitton.name>
> Date: Tue, 12 Apr 2022 11:43:30 -0700
> 
> Here's my docs patch if anyone has any comments.

Thanks for writing the documentation.

> +@defmac cl-with-gensyms names body@dots{}

Shouldn't @dots{} follow NAMES?  There's just one BODY, but any
number of NAMES, right?

> +This macro expands to code that executes @var{body} with each of the
> +variables in @var{names} bound to a fresh uninterned symbol or
> +``gensym''.

Instead of "or" I suggest to say "a.k.a.@: @dfn{gensym}" (and add a
@cindex entry for "gensym", as usual with any term in @dfn).

> +@defmac cl-once-only ((name form)@dots{}) body@dots{}
> +This macro is primarily to help the macro programmer ensure that forms
> +supplied by the user of the macro are evaluated just once by its
> +expansion even though the result of evaluating the form is to occur
> +more than once.  Less often, this macro is used to ensure that forms
> +supplied by the macro programmer are evaluated just once.
> +
> +Each @var{name} is a variable which can be used to refer to the result
> +of evaluating @var{form} in @var{body}.  @code{cl-once-only} binds
> +each @var{name} to a fresh uninterned symbol during the evaluation of
> +@var{body}.

My recommendation is always to try to name parameters after their
roles.  In this case, I'd use VAR or VARIABLE instead of the less
specific NAME.  Then you could make the text shorter and thus clearer:

  Each @var{variable} can be used to refer to the result of evaluating
  @var{form} in @var{body}.  @code{cl-once-only} binds each
  @var{variable} to a fresh uninterned symbol...

(And why not use "gensym" instead of the wordier "uninterned symbol"?
that's why you introduced that terminology, right?)

>            Then, @code{cl-once-only} wraps the final expansion in
> +code to evaluate each @var{form} and bind it to the corresponding
> +uninterned symbol.

How can a form be bound to a symbol?

> +In a call like @code{(my-list (pop foo) ...)} the intermediate binding
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Long stretches of @code which have embedded whitespace, like that one
above, should be  wrapped in @w{..}, to prevent them from being broken
between two lines.

Also, why a literal "..." instead of @dots{}?

> ++++
> +** New macro-writing macros, 'cl-with-gensyms' and 'cl-once-only'.

I suggest to add here a pointer to the node in the manual where they
are described, since this entry tells nothing about that to someone
who doesn't already know CL well enough.

Thanks.