GNU bug report logs - #32970
26; doc string of `this-command-keys-vector' (minor)

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 32970 in the body.
You can then email your comments to 32970 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26; doc string of `this-command-keys-vector' (minor)
Date: Sun, 7 Oct 2018 15:00:14 +0000 (UTC)

Doc string:

  this-command-keys-vector is a built-in function in 'C source code'.

  (this-command-keys-vector)

  Return the key sequence that invoked this command, as a vector.
  However, if the command has called 'read-key-sequence', it returns
  the last key sequence that has been read.

  See also 'this-command-keys'.
  This function does not change global state, including the match data.

It would be clearer, I think, if the order of the last two sentences
were reversed.  And perhaps they should not even be in the same
paragraph.  The current order can lead to thinking that "this function"
means `this-command-keys', and that it is only `this-command-keys', not
also `this-command-keys-vector', that does not change global state.

In GNU Emacs 26.1 (build 1, x86_64-w64-mingw32)
 of 2018-05-30
Repository revision: 07f8f9bc5a51f5aa94eb099f3e15fbe0c20ea1ea
Windowing system distributor `Microsoft Corp.', version 10.0.16299
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 32970 <at> debbugs.gnu.org
Subject: Re: bug#32970: 26; doc string of `this-command-keys-vector' (minor)
Date: Thu, 11 Jul 2019 17:55:35 +0200

Drew Adams <drew.adams <at> oracle.com> writes:

> Doc string:
>
>   this-command-keys-vector is a built-in function in 'C source code'.
>
>   (this-command-keys-vector)
>
>   Return the key sequence that invoked this command, as a vector.
>   However, if the command has called 'read-key-sequence', it returns
>   the last key sequence that has been read.
>
>   See also 'this-command-keys'.
>   This function does not change global state, including the match data.
>
> It would be clearer, I think, if the order of the last two sentences
> were reversed.  And perhaps they should not even be in the same
> paragraph.  The current order can lead to thinking that "this function"
> means `this-command-keys', and that it is only `this-command-keys', not
> also `this-command-keys-vector', that does not change global state.

The current help buffer is:

--

this-command-keys-vector is a built-in function in ‘src/keyboard.c’.

(this-command-keys-vector)

  This function does not change global state, including the match data.

Return the key sequence that invoked this command, as a vector.
However, if the command has called ‘read-key-sequence’, it returns
the last key sequence that has been read.

See also ‘this-command-keys’.
--

So this has been fixed.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 32970 <at> debbugs.gnu.org
Subject: RE: bug#32970: 26; doc string of `this-command-keys-vector' (minor)
Date: Thu, 11 Jul 2019 10:11:55 -0700 (PDT)

> >   this-command-keys-vector is a built-in function in 'C source code'.
> >
> >   (this-command-keys-vector)
> >
> >   Return the key sequence that invoked this command, as a vector.
> >   However, if the command has called 'read-key-sequence', it returns
> >   the last key sequence that has been read.
> >
> >   See also 'this-command-keys'.
> >   This function does not change global state, including the match data.
> >
> > It would be clearer, I think, if the order of the last two sentences
> > were reversed.  And perhaps they should not even be in the same
> > paragraph.  The current order can lead to thinking that "this function"
> > means `this-command-keys', and that it is only `this-command-keys', not
> > also `this-command-keys-vector', that does not change global state.
> 
> The current help buffer is:
> 
> --
> 
> this-command-keys-vector is a built-in function in ‘src/keyboard.c’.
> 
> (this-command-keys-vector)
> 
>   This function does not change global state, including the match data.
> 
> Return the key sequence that invoked this command, as a vector.
> However, if the command has called ‘read-key-sequence’, it returns
> the last key sequence that has been read.
> 
> See also ‘this-command-keys’.
> --
> 
> So this has been fixed.

For some definition of "fixed". ;-)

Yes, the original problem is gone.  Unfortunately, a
worse problem was introduced: putting that statement
about the match data before doc string itself.

Such info belongs at the end, but separated from
the doc string, e.g., by a horizontal line.

Anyway, yes, this can be closed.
(On n'arrete pas le progres.)

Previous Next

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