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

[Noam Postavsky]

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.
>
>> This conflates the reader macro with its particular use by the backquote
>> macro.
>
> The use by backquote isn't "a particular" use, as though there were
> several equally valid uses.  This use is the prime one, and up until
> fairly recently the only one.  Other uses are subsidiary (and I make
> reference to the other one lower down).

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

>
>> I think it's better to explain only the reader macro here, and
>> link to ` and pcase for more details.
>
> In other words, omit the semantics from the doc string.  I don't think
> that's a good idea: "This macro transforms `foo' into ....., but you'll
> have to look up ..... to see what it actually does.".  We don't do that
> for macros like `when' and `unless', or any others I can think of, so
> why do it for ,?

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

>
>> > +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.

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