bug#3936: 23.0.96; doc string of called-interactively-p

bug#3936: 23.0.96; doc string of called-interactively-p

[Drew Adams]

Doc string:
 
"Return t if the function using this was called with
`call-interactively'."
 
The function using this? Using what?
This sentence doesn't make sense.
 

In GNU Emacs 23.0.96.1 (i386-mingw-nt5.1.2600)
 of 2009-07-09 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 

bug#3936: 23.0.96; doc string of called-interactively-p

[Bastien]

"Drew Adams" <drew.adams@oracle.com> writes:

> "Return t if the function using this was called with
> `call-interactively'."

I replaced this by :

  Return t if it is in a function called with `call-interactively'.

Thanks,

-- 
 Bastien

bug#3936: 23.0.96; doc string of called-interactively-p

[Drew Adams]

> > "Return t if the function using this was called with
> > `call-interactively'."
> 
> I replaced this by :
> 
>   Return t if it is in a function called with `call-interactively'.

That's just as bad. What's "it"?

I really don't understand what you are trying to say. When does
`called-interactively-p' return t? It should be possible to describe that
condition. What does the code say?

bug#3936: 23.0.96; doc string of called-interactively-p

[Bastien]

"Drew Adams" <drew.adams@oracle.com> writes:

>> > "Return t if the function using this was called with
>> > `call-interactively'."
>> 
>> I replaced this by :
>> 
>>   Return t if it is in a function called with `call-interactively'.
>
> That's just as bad. 

Thanks. :)

> What's "it"?

Usually "it" in a docstring refers to the function/variable the
docstring is documenting.  At least this is how I understand it.

> 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.

> When does `called-interactively-p' return t?

When the function in which (call-interactively-p) is has been
interactively called with (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.

-- 
 Bastien

bug#3936: 23.0.96; doc string of called-interactively-p

[Drew Adams]

> > 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.

bug#3936: 23.0.96; doc string of called-interactively-p

[Bastien]

"Drew Adams" <drew.adams@oracle.com> writes:

> 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.

Thanks,

-- 
 Bastien

bug#3936: 23.0.96; doc string of called-interactively-p

[Drew Adams]

> > 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.

bug#3936: marked as done (23.0.96; doc string of called-interactively-p)

[Emacs bug Tracking System]

[-- Attachment #1: Type: text/plain, Size: 876 bytes --]


Your message dated Sat, 15 Aug 2009 17:53:07 -0400
with message-id <877hx4n3r0.fsf@cyd.mit.edu>
and subject line Re: 23.0.96; doc string of called-interactively-p
has caused the Emacs bug report #3936,
regarding 23.0.96; doc string of called-interactively-p
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
3936: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=3936
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 3061 bytes --]

From: "Drew Adams" <drew.adams@oracle.com>
To: <emacs-pretest-bug@gnu.org>
Subject: 23.0.96; doc string of called-interactively-p
Date: Sun, 26 Jul 2009 13:56:22 -0700
Message-ID: <09B238050EFB472EBBBFDCFF9B184113@us.oracle.com>

Doc string:
 
"Return t if the function using this was called with
`call-interactively'."
 
The function using this? Using what?
This sentence doesn't make sense.
 

In GNU Emacs 23.0.96.1 (i386-mingw-nt5.1.2600)
 of 2009-07-09 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (3.4)'
 



[-- Attachment #3: Type: message/rfc822, Size: 1132 bytes --]

From: Chong Yidong <cyd@stupidchicken.com>
To: 3936-done@emacsbugs.donarmstrong.com
Subject: Re: 23.0.96; doc string of called-interactively-p
Date: Sat, 15 Aug 2009 17:53:07 -0400
Message-ID: <877hx4n3r0.fsf@cyd.mit.edu>

I've checked in fixes for the doc strings of interactive-p and
called-interactively-p, which should make them clearer.