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

[Alan Mackenzie]

Hello, Noam.

On Thu, Jan 19, 2017 at 01:10:24PM -0500, Noam Postavsky wrote:
> On Thu, Jan 19, 2017 at 12:37 PM, Alan Mackenzie <acm@muc.de> wrote:

> >> > +;; Give `,' and `,@' documentation strings which can be examined by C-h 
> >> > f.
> >> > +(put '\, 'function-documentation
> >> > +     "`,' signals that the next form should be evaluated and inserted.

[ .... ]

> I agree backquote is the primary use, it's reasonable to emphasize that.

> Because "," isn't a macro, it doesn't have any semantics. It's
                                        ^^^^
> misleading to suggest that it does.

We could degenerate into a long silly discussion about what "have" means.
, evaluates the form it precedes, and inserts it into the containing
list.  That's semantics enough for me.

> >> > +It can occur only in `\\=`' constructs.

> >> This isn't true.

> > In what sense is it not true?  I've never seen a comma used otherwise in
> > a lisp program.  What misunderstanding could it cause in a (relatively
> > new) Lisp hacker reading it?

> In the sense that it's possible to write a macro that could treat the
> "," differently. I don't know of any that currently do*, but that's
> just convention and should be documented as such.

OK, I've toned down that part of the doc string.  (See below.)

> * `use-package' once handled unmatched "," as signifying eager
> evaluation, but it no longer does that.

How about this, then:

        "`,' signals that the next form should be evaluated and inserted.
    It occurs in `\\=`' constructs.

    For example:

    b              => (ba bb bc)            ; assume b has this value
    \\=`(a ,b c)      => (a (ba bb bc) c)   ; insert the value of b

    See also `\\=`' and `,@'.

    (Note that ``' constructs (including `,'s) sometimes have different
    semantics.  This occurs, for example, with the macro `pcase' and other
    macros with similar names.)

?

-- 
Alan Mackenzie (Nuremberg, Germany).