[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#25461: [Patch]: Missing doc strings for "," and ",@".
From: |
Noam Postavsky |
Subject: |
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@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.
- bug#25461: Missing doc strings for "," and ",@"., (continued)
- bug#25461: Missing doc strings for "," and ",@"., Glenn Morris, 2017/01/17
- bug#25461: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/17
- bug#25461: Missing doc strings for "," and ",@"., Andreas Schwab, 2017/01/17
- bug#25461: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/17
- bug#25461: Missing doc strings for "," and ",@"., Andreas Schwab, 2017/01/17
- bug#25461: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/17
- bug#25461: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/18
Message not available
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/18
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., npostavs, 2017/01/18
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@".,
Noam Postavsky <=
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/19
- bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/19
bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/18
bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/19
bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/19
bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/20
bug#25461: [Patch]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/20
bug#25461: [Patch]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/21
bug#25461: [Patch #2]: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/21
bug#25461: [Patch #2]: Missing doc strings for "," and ",@"., Michael Heerdegen, 2017/01/23