bug#13373: 24.3.50; doc string of `execute-extended-command' is incorrect

[Drew Adams]

The doc string is incorrect and misleading in several ways.
 
 Read function name, then read its arguments and call it.
 
 To pass a numeric argument to the command you are invoking with, specify
 the numeric argument to this command.
 
 Noninteractively, the argument PREFIXARG is the prefix argument to
 give to the command you invoke, if it asks for an argument.
 
1. It is not just a function name that is read.  It is (it must be) a
COMMAND name, i.e., an interactive function.
 
2. `execute-extended-command' does NOT read the arguments of the
"function name" it reads.  First, a function NAME does not have any
arguments.  Second, it is the command so named that reads its own
arguments, if any are read.  `e-e-c' does nothing of the kind.
 
3. (What prompted me to write this bug report.)  It is not about passing
a "numeric argument" to the command invoked by `e-e-c'.  It is about
passing it THE prefix argument, in fact the RAW prefix argument.
 
There is a LOT of confusion in this doc string.  Almost everything it
says is wrong or misleading.
 

[Also:
 
4. There is no reason to skip a line after the first doc line.  That is
not the Emacs convention.
 
5. The second sentence is grammatically incorrect.  "...to the command
you are invoking with" - invoking WITH? invoking with what?
 
6. The third sentence is confusing.  "if it asks for an argument".  No
command ever asks the user for a prefix argument.  Presumably what is
meant is "if it accepts a prefix argument."
 
Anyway, the second and third sentences are verbose and somewhat
repetitive.]

 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2012-12-31 on ODIEONE
Bzr revision: 111388 rudalics@gmx.at-20121231113513-subz2dazg6yjukzh
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'