bug#14577: 24.3.50; doc string of `interactive' is wrong

bug#14577: 24.3.50; doc string of `interactive' is wrong

[Drew Adams]

The doc string confuses wrt its optional argument.  Please refer to
(elisp) `Using Interactive' for a proper description, the essentials of
which can be used to fix the doc string.

1. There is one optional argument, which should not be called ARGS, as
that confuses things.  If there is an argument for `interactive' then
there is only one.  The optional argument to `interactive' provides the
arguments to the command.  The Elisp manual calls the `interactive'
argument ARG-DESCRIPTOR, which is OK.

2. "To get several arguments" - Again, such language is
misleading/confusing.  The doc string tries to use "argument" in more
than one sense, without distinguishing or defining them.  IOW, if you
want to speak about the arguments that get passed to the command (not to
`interactive'), then be careful about the wording.

3. "it is evaluated to get a list of arguments to pass to the function".
Say "command", not "function", here, to avoid confusion with the
argument to `interactive'.  Better is to avoid such language altogether.


In GNU Emacs 24.3.50.1 (i386-mingw-nt6.1.7601)
 of 2013-06-01 on ODIEONE
Bzr revision: 112809 xfq.free@gmail.com-20130601123514-of64qkop6z48i3ko
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'

bug#14577: 24.3.50; doc string of `interactive' is wrong

[Lars Ingebrigtsen]

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

> The doc string confuses wrt its optional argument.  Please refer to
> (elisp) `Using Interactive' for a proper description, the essentials of
> which can be used to fix the doc string.
>
> 1. There is one optional argument, which should not be called ARGS, as
> that confuses things.  If there is an argument for `interactive' then
> there is only one.  The optional argument to `interactive' provides the
> arguments to the command.  The Elisp manual calls the `interactive'
> argument ARG-DESCRIPTOR, which is OK.
>
> 2. "To get several arguments" - Again, such language is
> misleading/confusing.  The doc string tries to use "argument" in more
> than one sense, without distinguishing or defining them.  IOW, if you
> want to speak about the arguments that get passed to the command (not to
> `interactive'), then be careful about the wording.
>
> 3. "it is evaluated to get a list of arguments to pass to the function".
> Say "command", not "function", here, to avoid confusion with the
> argument to `interactive'.  Better is to avoid such language altogether.

I've now tweaked this on the trunk.

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