GNU bug report logs - #3936
23.0.96; doc string of called-interactively-p

Previous Next

Full log

View this message in rfc822 format

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Bastien'" <bastienguerry <at> googlemail.com>
Cc: <3936 <at> debbugs.gnu.org>, <emacs-pretest-bug <at> gnu.org>
Subject: bug#3936: 23.0.96; doc string of called-interactively-p
Date: Mon, 27 Jul 2009 01:18:45 -0700

> > I really don't understand what you are trying to say. 
> 
> Are you sure?  Even the name of this function is very explicit:
> "call-interactively-p", and I bet you know what it does - so it
> shouldn't be hard to guess what the docstring is trying to say.

(`called-interactively-p', not `call-interactively-p'.) And no, I don't know
exactly what it does - its C code is hard for me to follow.

Here is what the doc string of `interactive-p' said, back in Emacs 20-21:

"Return t if function in which this appears was called interactively."

That's a little clearer, though it too speaks of "this". To me, "in which this
appears" is clearer than "using this".

> > When does `called-interactively-p' return t?
> 
> When the function in which (call-interactively-p) is has been
> interactively called with (call-interactively ...)

"_interactively_ called with (call-interactively...)" Is it a joke? How about
just "called using `call-interactively'"?

> > It should be possible to describe that
> > condition. What does the code say?
> 
> Please suggest something better - with this small annoying constraints
> that the first line has to be quite short.

The first line has to be short. The rest doesn't have to be short. See what was
said before for `interactive-p' - it's not too bad.  

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.

See also bug #3941, preferably before fixing this doc string. The doc of both of
these functions is a mess in general, IMO.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.