[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#25462: Out of date doc string for "`".
From: |
npostavs |
Subject: |
bug#25462: Out of date doc string for "`". |
Date: |
Tue, 17 Jan 2017 21:04:48 -0500 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) |
Alan Mackenzie <acm@muc.de> writes:
> Hello, Noam.
>
> On Mon, Jan 16, 2017 at 04:52:36PM -0500, Noam Postavsky wrote:
>> On Mon, Jan 16, 2017 at 4:30 PM, Alan Mackenzie <acm@muc.de> wrote:
>> > Hello, Emacs.
>
>> > The doc string for "`" has become partial.
>
>> > It fails to mention that "`" has a radically different meaning when used
>> > in certain parts of a `pcase', and probably quite a few other similar
>> > macros.
>
>> I don't think that makes sense. Similarly, we don't add a mention of
>> `cl-loop's use of `if' in the docstring of `if', because that's not
>> part of the `if' special form. It's just a use of `if' as a plain
>> symbol.
>
> I don't think `if' inside cl-loop is liable to cause much confusion.
> pcase, on the other hand, does cause confusion, as it radically changes
> the meaning of symbols contained within it, something that other macros
> don't do - with the possible minor exception of cl-loop.
>
> If you can think of any other such examples of context dependence
> changing the semantics, I think these should be documented too.
`rx' gives new semantics to `and', `or', `any', etc...
`condition-case' changes the meaning of the symbol list at the front of
its handlers.
At one point, the `use-package' macro (note, this is not (yet) part of
Emacs) interpreted `,' to mean eager evaluation. But people didn't like
it, so it now uses `lambda' for that instead.
> The direction I'm coming from is to make the doc strings help users -
> not to make them 100% consistent.
Well, I guess adding a mention of pcase in backquote's docstring would
be okay. The way your initial report phrases it, as if the docstring is
incomplete without that, didn't make sense to me.