Re: The poor state of documentation of pcase like things.

[Eli Zaretskii]

> From: Michael Heerdegen <address@hidden>
> Cc: address@hidden,  address@hidden,  address@hidden
> Date: Sun, 03 Jan 2016 05:21:48 +0100
> 
> > Are you serious?  We've just had a long discussion about its missing
> > or incomplete or inadequate documentation,
> 
> I know that, but that we can and want to fix, so it is no argument about
> whether pcase is really eval or not.

The discussion is IMO a clear indication that at least some people
have difficulties reading the code which involves 'pcase'.  Which
means, IMO, that it shouldn't be used where simpler, more clear forms
will do.

> > including a long dispute about whether it would be better to quote _.
> 
> Yes, and...???

And that was IMO a clear indication that even the tiniest syntax
issues related to 'pcase' raise problems.

> > My summary of that discussion is that the syntax is complicated and
> > quite weird.
> 
> Where did we at all talk about the syntax?

If the semantics are not clear, the syntax is the first suspect.

> > Using such a beast where it is not required makes reading harder
> > because it requires the reader to understand its syntax, if nothing
> > else.
> 
> And that's the real problem: (some) people refrain to try to understand
> the syntax and prefer to complain.

That's not my concern.  I'm not one of those people.

> Sorry, I give up.  pcase seems to scare off people somehow.  If 50
> percent of the people are not able to cope with the thing, for whatever
> reason, and get stalled whenever they see it, I think we probably can't
> use it.  A pity.

I never said anything even close to such an extreme.  I don't think
there's any danger of refraining to use 'pcase' any time soon.  It
does its job well, and where it's needed, it should definitely be
used.

> Is it even worth to update the docs of pcase?

Yes, definitely.  With the current proliferation of its use in our
sources, we cannot leave it under-documented.  I hope to see proposals
for documentation patches soon, thank you.

> Will anyone from those antagonizing it really try to learn how the
> thing is supposed to be used?

I'm sure more than one will, indeed.

Thanks.