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

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

[Drew Adams]

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''

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

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

[Drew Adams]

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