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

[Lars Ingebrigtsen]

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

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

Fixed on trunk.

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