Re: pcase docs

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: address@hidden,  address@hidden
> Date: Sat, 23 Jan 2016 11:16:01 +0100
> 
> Eli Zaretskii <address@hidden> writes:
> 
> > Since we don't have a separate "Emacs Lisp for Developers of Internal
> > Packages" manual, I don't see why we should omit these or describe
> > them in less detail.
> 
> I didn't mean it like that.  But I think we can assume that they will
> already know how `defmacro' works - something I would not assume for
> every user of Emacs.

Sorry, I don't understand: how can knowing what 'defmacro' does help
to know what 'pcase-defmacro' does?  At the very least, one needs to
know which patterns will be possible after using 'pcase-defmacro',
don't you agree?

Btw, this macro also has "issues".  The doc string is less than
helpful:

    "Define a new kind of pcase PATTERN, by macro expansion.
  Patterns of the form (NAME ...) will be expanded according
  to this macro."

It says nothing about ARGS, and the "by macro expansion" part sounds
strange -- what useful information does it supply here?

And if you turn to the users of this macro, in the hope of gaining
some understanding, you will see, for example, that map.el defines a
pattern whose NAME is "map":

  (pcase-defmacro map (&rest args)
    "Build a `pcase' pattern matching map elements.

  The `pcase' pattern will match each element of PATTERN against
  the corresponding elements of the map.

(btw: what PATTERN?), but then uses it like this:

  (pcase type
    (`list (map-pairs map))
    (`hash-table (map--into-hash-table map))
    (_ (error "Not a map type name: %S" type))))

IOW, it actually uses sub-classes of 'map' as patterns.  Hmm...

(You can now understand why the documentation of 'pcase-defmacro' I
added is rather laconic and in some sense unsatisfactory.)

As an aside, when I look at such doc strings, I always become
frustrated, because I must be extremely stupid to ask all these
questions, when no one else evidently cares, which must mean they all
understand this stuff, and only I alone don't, right?

Thanks.