bug#35228: 26.1; Please consider adding a doc string for `extended-command-history'

bug#35228: 26.1; Please consider adding a doc string for `extended-command-history'

[Drew Adams]

Subject line says it all.

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.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#35228: 26.1; Please consider adding a doc string for `extended-command-history'

[Basil L. Contovounesios]

[-- Attachment #1: Type: text/plain, Size: 22 bytes --]

How's the following?


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: history.diff --]
[-- Type: text/x-diff, Size: 585 bytes --]

diff --git a/lisp/simple.el b/lisp/simple.el
index 223e0116ae..5977f6c035 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -1713,7 +1713,11 @@ repeat-complex-command
 	(error "There are no previous complex commands to repeat")))))
 
 
-(defvar extended-command-history nil)
+(defvar extended-command-history nil
+  "History list for extended command name arguments.
+It is used by `execute-extended-command', and its maximum length
+is determined by the value of `history-length', which see.")
+
 (defvar execute-extended-command--last-typed nil)
 
 (defun read-extended-command ()

[-- Attachment #3: Type: text/plain, Size: 20 bytes --]


Thanks,

-- 
Basil

bug#35228: 26.1; Please consider adding a doc string for `extended-command-history'

[Drew Adams]

> How's the following?

OK.  But I think it should say that it's a history list
for functions, such as `read-from-minibuffer', that read
input in the minibuffer.

It should perhaps also say that the commands in question
are Emacs commands (as opposed to, say, shell commands or
whatever).  That's what "extended command" means, but it
wouldn't hurt to make this clear.

BTW, the Elisp manual says (only) this:

"A history list for arguments that are names of extended
commands."

That's in node `Minibuffer History', which covers what is
involved generally (so it should cover what "arguments"
means here).

However, I think it's wrong for the descriptions in that
node to speak of "arguments".  There is only ever one
HISTORY arg for any given minibuffer-reading function call.
What's said now is unclear, I think.  It would be good to
fix this language too.

Anyway, for this doc string how about something like this?

"Minibuffer history list for names of Emacs commands.
It is used by function `execute-extended-command'.
An Emacs command is anything that satisfies predicate `commandp'.
A minibuffer history list is used by functions such as
`read-from-minibuffer' that read input in the minibuffer.
The maximum effective length of such a list is controlled by the value
of variable `history-length'."

Do we need to mention `history-length' or to remind users
what a minibuffer history and an Emacs command are?  Perhaps
not, but it doesn't hurt.

bug#35228: 26.1; Please consider adding a doc string for `extended-command-history'

[Lars Ingebrigtsen]

"Basil L. Contovounesios" <contovob@tcd.ie> writes:

> How's the following?

[...]

> -(defvar extended-command-history nil)
> +(defvar extended-command-history nil
> +  "History list for extended command name arguments.
> +It is used by `execute-extended-command', and its maximum length
> +is determined by the value of `history-length', which see.")

I kinda think this is unnecessary -- we have a gazillion history
variables in Emacs, and adding doc strings to them all is pretty
pointless -- it's self-evident what they're used for.

So I'm closing this bug report.

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