bug#31311: 27.0; doc of `pcase'

[Drew Adams <drew.adams@oracle.com>]

> > Perhaps you can at least remove the incomprehensible and
> > seemingly unrelated text (I cited) that appears at the end
> > of the doc string, as a start.
> 
> This is not unrelated: These are the docs for additional pcase patterns
> defined elsewhere: pcase is extensible, and the pattern listing part in
> the docstring is generated dynamically.  As a result of that conception
> it may not read very fluently as a whole, but it's definitely nothing we
> want to remove.

Sorry, but that extra (dynamically generated?) text at the
end makes no sense at all to me.  I don't have a clue what
it's trying to convey.  To me it's just noise that can only
confuse, not help, users.

If there is some core meaning behind it then great.  In
that case there is a potential for it to say something.

That's not happening at all now, I think.  For the time
being, i.e., until someone can translate that core meaning
(what you really expect it to be trying to say) into
understandable text, it should be removed.  Please consider
moving it to a TODO item somewhere, if you like.  But maybe
others disagree and only I have trouble seeing what that
text is all about.

Beyond that, if it is about showing examples of defining
additional `pcase' patterns in the Emacs code then I
don't think that kind of thing belongs in a doc string -
certainly not multiple such examples.

Even in the Elisp manual, I'd expect only a simple example
of defining a `pcase' pattern, in the node itself.  If it
were thought to really be helpful then there could perhaps
also be a note to see the code of this or that function.
But I really don't expect that that should be necessary.
Do we do that anywhere else?

Either it is simple to define your own `pcase' patterns
or it is not.  If it is, then no such extra examples
should be needed.  If it's not, then can't we make it
easier to define your own patterns (change the product,
not just the doc)?

From what you are saying, it sounds to me like what users
need to make sense of `pcase' is a blog article, showing
examples etc. and building up from simple to complex.
I'd rather encourage someone to write that than for us
to try to cram such info into a doc string or manual node.
 
> We clearly have some deficiencies, but the situation IMHO really is not
> as horrible as Eli's sarcasm suggests.

FWIW, I don't see what Eli wrote as sarcasm.  I do see it
as negative, nearly despondent.  But sarcasm involves some
element of humor, irony, or satire, which I don't find there.

In any case, there are two different problems being
discussed so far in this thread: (1) the doc is bad, and
(2) it has been given insufficient love.

This bug is really about #1.  But according to Eli, #1
likely won't be fixed because of #2.  Dunno whether he
is right, but #1 is the problem to report.