Re: Weird &key arglists in ibuf-macs.el

[Lawrence Mitchell <wence@gmx.li>]

Juanma Barranquero wrote:

> ibuf-macs.el contains a few macros with CL-style arglists of the form

>   (defmacro* macro1 (arg1 arg2 (&key arg3 arg4)...)

> instead of

>   (defmacro* macro1 (arg1 arg2 &key arg3 arg4...)

> I'm not sure that's a legal CL lambda list

It is legal, see section 3.4.4.1 of the hyperspec <URL:
http://www.lispworks.com/reference/HyperSpec/Body/03_dda.htm>.

|  Anywhere in a macro lambda list where a parameter name can
|  appear, and where ordinary lambda list syntax (as described in
|  Section 3.4.1 (Ordinary Lambda Lists)) does not otherwise allow
|  a list, a destructuring lambda list can appear in place of the
|  parameter name. When this is done, then the argument that would
|  match the parameter is treated as a (possibly dotted) list, to
|  be used as an argument list for satisfying the parameters in the
|  embedded lambda list. This is known as destructuring.

It's often used for with-FOO type macros, e.g.

(defmacro* with-foo ((&key x y z &rest stuff) &body more-stuff)
  ...)

allowing

(with-foo (:x x :y y :z z (more-stuff))
  (doing-more-stuff))

> help-make-usage and company don't grok them:

> ELISP> (documentation (defmacro* test1 (arg1 &key arg2) "No doc"))
> "No doc\n\n(fn ARG1 &key ARG2)"
> ELISP> (documentation (defmacro* test1 (arg1 (&key arg2)) "No doc"))
> "No doc\n\n(fn ARG1 (&KEY arg2))"

The thing to do here is to explicitly write the arglist in the
end of the docstring.

(documentation (defmacro* test1 (arg1 (&key arg2))
                  "No doc\n\n(fn ARG1 (&key ARG2))"))
   => No doc\n\n(fn ARG1 (&key ARG2))

-- 
Lawrence Mitchell <wence@gmx.li>