bug#30958: 26.0.91; No documentation for key and value in the function passed to `map-keymap'

[Stefan Kangas <stefan@marxist.se>]

Hong Xu <hong@topbug.net> writes:

> Thanks, Drew. Actually it's also obvious for me to look up for a keymap
> is. What is unobvious is the value of the binding. Even if you go to
> "Format of Keymaps", it still does not talk about the actual value of
> the binding. The reason it is important for `map-keymap' is that this
> seems to be the only place that users need to know the exact value of
> binding---in other places, they are operated by some provided functions.

The docstring of `map-keymap' says:

    Call FUNCTION once for each event binding in KEYMAP.
    FUNCTION is called with two arguments: the event that is bound, and
    the definition it is bound to.  The event may be a character range.

A keymap is fundamentally either a list or a char table with
mappings from events to a definition.  The event could be e.g. a key
sequence, and the definitions might be commands or other things.

I find "the event that is bound" to be clear enough, in the sense that
you know what to look for in the manual.

I also find "the definition it is bound to" clear in the same sense.

I don't see what to add to make this any clearer, without pulling in the
entire reference manual worth of stuff to explain all possible types of
values.  IOW, I think the answer here is that to use this particular
function, you cannot just read the docstring, you must study the info
node `(elisp) Keymaps' in detail.  I don't see any way around that.

So maybe you are right, but maybe also there is just not much we can do
about it.  Or there is some way to explain this that none of us have
seen so far.  Perhaps you have a suggestion for what we could add here?