bug#25461: Missing doc strings for "," and ",@".

[Alan Mackenzie <acm@muc.de>]

Hello, Michael.

On Wed, Jan 18, 2017 at 02:44:28AM +0100, Michael Heerdegen wrote:
> Alan Mackenzie <acm@muc.de> writes:

> > I don't expect the typical novice Elisp hacker cares about such nice
> > distinctions.  She can get a doc string for `, so why not one for , or
> > ,@?

> ' and #' also "don't have a docstring".  That ` "has a docstring" is
> just coincidence - because the reader transforms

>   `expr

> to

>   (` expr)

> and the symbol ` has an associated symbol-function.

I'm sure that's true.  But ' is not really difficult enough to need a
doc string (IMAO).  Well, it didn't used to be, before it became
(ab)used by pcase.  #' could certainly do with one, I think.

But in my patch (which I expect to post within a few minutes of this
post), I have created a mechanism by which other reader macros can have
doc strings added.

> FWIW when I first saw `, , and ,@, it looked strange enough to me to
> open the manual, because the syntax seemed so unusual that I believed
> that I missed an essential part of knowledge about Elisp.  At least this
> is what I think happened...

Yes, but unless you're a genius, you probably had to look at the manual
several times before you internalised the meaning of , and ,@, with a
fair bit of practice in between.  During that practice, you might well
have found opening the manual to have been a hassle which you could have
avoided, had there been doc strings at the time.

> But I agree that some people might try C-h f on any of these, and we
> would not all die if we would show something useful in this case.  We
> could just say that C-f explains symbol functions and "reader macros"
> and the thing would still be consistent.

Or, not say anything at all - just do it.  C-h f after all does explain
named functions.  That it also explains a couple of reader macros as a
bonus hardly needs going on about.

> OTOH, I think that saying anything about `pcase' there would be a bad
> idea.

I disagree.  I was confused fairly badly for a long time when pcase
appeared (without announcement, IIRC) and purloined the reader macros
which, up till then, had had single definite functionalities.  I assume
other people were and will be confused by pcase usages, so it will do no
harm to draw people's attention towards them.  Anyhow, I've included a
sentence about pcase at the end of the proposed doc string for ,.  I
don't think pcase uses ,@, or at least I haven't seen any such use of it.

> Michael.

-- 
Alan Mackenzie (Nuremberg, Germany).