GNU bug report logs - #25461
Missing doc strings for "," and ",@".

Previous Next

Full log

Message #44 received at 25461 <at> debbugs.gnu.org (full text, mbox):

From: Noam Postavsky <npostavs <at> users.sourceforge.net>
To: Alan Mackenzie <acm <at> muc.de>
Cc: 25461 <at> debbugs.gnu.org
Subject: Re: bug#25461: [Patch]: Missing doc strings for "," and ",@".
Date: Thu, 19 Jan 2017 13:10:24 -0500

On Thu, Jan 19, 2017 at 12:37 PM, Alan Mackenzie <acm <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.