[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#25461: Missing doc strings for "," and ",@".
From: |
Alan Mackenzie |
Subject: |
bug#25461: Missing doc strings for "," and ",@". |
Date: |
Wed, 18 Jan 2017 19:28:48 +0000 |
User-agent: |
Mutt/1.5.24 (2015-08-30) |
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).
- bug#25461: Missing doc strings for "," and ",@"., Alan Mackenzie, 2017/01/16
- 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 <=
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, 2017/01/19
- 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