Re: Replace trivial pcase occurrences in the Emacs sources

[Andy Moreton]

On Tue 30 Oct 2018, Alan Mackenzie wrote:

> Hello, Stefan.
>
> On Tue, Oct 30, 2018 at 14:17:10 -0400, Stefan Monnier wrote:
>> > Not everybody is familiar with dolist by any means.  Is dolist's doc
>> > string of sufficiently high quality to act as this basis?
>
>> If dolist's docstring is not good enough, then I don't think it's
>> pcase-dolist's job to fix it.
>
> I think everybody would agree with this point.
>
>> >> We do have to keep the reference to `pcase` because we don't want to
>> >> repeat the definition of what a pcase pattern can look like.
>
>> > Yes, I think that's right.
>
>> > Things I believe MUST appear explicitly in the doc string for
>> > pcase-dolist: 
>> > 1. It is a loop over the elements of LIST, which must be a list.
>> > 2. It attempts to match the current list element with the supplied
>> > PATTERN, which must be a valid pcase style pattern.
>> > 3. The BODY forms are evaluated for each element of the list.
>> > 4. The purpose of the matching is to create bindings for symbols, and
>> > these bindings are in force when the BODY forms are evaluated.
>> > 5. When a pattern match fails, ..... (This needs to be stated).
>
>> This is highly redundant w.r.t pcase-let and dolist.
>
> Maybe, but so what?
>
> Doc strings should be as far as is reasonable self contained.  Have a
> look at the doc strings for let and let*.  They have a great deal in
> common, but each is self contained.

Exactly. For the pcase macros, the docstrings need to describe what the
arguments are, and what the macro actually does. A reference to `pcase'
itself to describe the patterns is fine.  The last thing in the
docstring should be a reference to the similarly named non-pcase
construct with similar behaviour (which is the least important part).

>> Fine for the manual, but not for docstrings.
>
> You seem to be arguing that doc strings needn't say what
> de{fun,macro,var}s do and are, as long as the meaning can be acquired
> through the traversal of a directed acyclic graph of linked doc strings.
> Maybe you find this a good way of acquiring information, but I certainly
> don't.  I just get angry and frustrated, and I'm sure I'm not the only
> one.

Me too. Docstrings are to educate and inform users, and lead them to
discover new functionality (and hopefully read the manual for more
detailed discussion). A little redundancy of presentation is actually a
good thing if it aids the understanding of non-experts who are trying to
learn.

    AndyM