Re: Docstring for define-key

[Richard Stallman <rms@gnu.org>]

    But another wording could be used to fulfill the convention:

    Define, in KEYMAP, key sequence KEY as DEF.

I think these words would be clearer:

    But another wording could be used to fulfill the convention:

    Define, in keymap KEYMAP, key sequence KEY with definition DEF.

It is a good practice to say explicitly what kind of value each arg
has even if its name states the type, because the name does
not always state the type.

    > The convention is that the first line of the doc string should mention
    > the (non-optional) arguments in the actual sequence.

    I doubt that was the reason.  More likely the redundant text was
    put there before `C-h f' started to automatically add the
    (define-key KEYMAP KEY DEF) usage.

I would expect it was a combination of both reasons.

I will add this to the Documentation Tips node in the Lisp ref manual.

@item
The first line should mention all the important arguments of the
function, and should mention them in the order that they are written
in a function call.  If the function has many arguments, then it is
not feasible to mention them all in the first line; then the first
line should mention the first few arguments, including the most
important arguments.