Re: Docstring for define-key

["Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>]

> Juanma Barranquero <lektu@terra.es> writes:
> 
> > On Thu, 20 Feb 2003 20:58:19 +0100, kai.grossjohann@uni-duisburg.de (Kai Großjohann) wrote:
> > 
> > > I changed it accordingly.
> > 
> > On the matter of define-key's docstring, the beginning:
> > 
> > "Args KEYMAP, KEY, DEF.  Define key sequence KEY, in KEYMAP, as DEF.
> > KEYMAP is a keymap.
> > 
> > [...]"
> > 
> > is a bit redundant, isn't? What's wrong with:
> > 
> > "Define key sequence KEY, in keymap KEYMAP, as DEF.
> 
> 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 don't think it's important at all whether arguments are listed in the
"proper" order or not.  It's much more important that the text be
clear, concise, precise, simple.


	Stefan