GNU bug report logs - #25462
Out of date doc string for "`".

Previous Next

Full log

View this message in rfc822 format

From: Alan Mackenzie <acm <at> muc.de>
To: Noam Postavsky <npostavs <at> users.sourceforge.net>
Cc: 25462 <at> debbugs.gnu.org
Subject: bug#25462: Out of date doc string for "`".
Date: Tue, 17 Jan 2017 20:05:39 +0000

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

The direction I'm coming from is to make the doc strings help users -
not to make them 100% consistent.

-- 
Alan Mackenzie (Nuremberg, Germany).

Previous Next

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