[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#3936: 23.0.96; doc string of called-interactively-p
From: |
Drew Adams |
Subject: |
bug#3936: 23.0.96; doc string of called-interactively-p |
Date: |
Mon, 27 Jul 2009 09:04:17 -0700 |
> > In particular, the doc strings of `called-interactively-p'
> > and `interactive-p' should, together, make clear their
> > difference. They can't both just say that they test for
> > an interactive call. They need to speak about keyboard
> > macro use as the difference in behavior.
>
> Please suggest a docstring for both these functions.
> If your suggested dosctrings are clearer, we will clearly see it.
>
> By trying to explain in a very wordy fashion what is *not*
> clear to you, you're at risk of not being clear yourself.
I think I was clear enough. Fix the Elisp manual first; the doc strings will
follow easily. If you don't understand what I wrote or are unwilling to work on
it, perhaps someone else will.
The doc is not just unclear; it is wrong/bad, as I pointed out specifically.
In addition to the doc problems I listed, there is a non-doc problem: Whoever
came up with the new function (in Emacs 22) `called-interactively-p' did the
wrong thing, IMO.
That function name tells nothing more nor less than the name `interactive-p' -
there is nothing in the names that distinguishes these functions. Might as well
have named the new function `interactive-p-2' (no, it's not a suggestion).
It would have been far better to add an optional argument to `interactive-p'
than to create a new, similarly named function. For example:
(defun interactive-p (&optional k-macro-p)
"Return t if function in which this appears was called interactively.
If optional arg K-MACRO-P is non-nil, return t when called during
execution of a keyboard macro. If it is nil, return nil in that case.
...[rest of description]"
I vote for deprecating one or the other of these two functions, combining them
by using an optional argument to express the alternative behaviors. That will go
a long way toward clarifying the intended uses.