* bug#3936: 23.0.96; doc string of called-interactively-p @ 2009-07-26 20:56 ` Drew Adams 2009-07-27 2:03 ` Bastien 2009-08-15 22:00 ` bug#3936: marked as done (23.0.96; doc string of called-interactively-p) Emacs bug Tracking System 0 siblings, 2 replies; 8+ messages in thread From: Drew Adams @ 2009-07-26 20:56 UTC (permalink / raw) To: emacs-pretest-bug 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)' ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3936: 23.0.96; doc string of called-interactively-p 2009-07-26 20:56 ` bug#3936: 23.0.96; doc string of called-interactively-p Drew Adams @ 2009-07-27 2:03 ` Bastien 2009-07-27 6:24 ` Drew Adams 2009-08-15 22:00 ` bug#3936: marked as done (23.0.96; doc string of called-interactively-p) Emacs bug Tracking System 1 sibling, 1 reply; 8+ messages in thread From: Bastien @ 2009-07-27 2:03 UTC (permalink / raw) To: Drew Adams; +Cc: emacs-pretest-bug, 3936 "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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3936: 23.0.96; doc string of called-interactively-p 2009-07-27 2:03 ` Bastien @ 2009-07-27 6:24 ` Drew Adams 2009-07-27 6:43 ` Bastien 0 siblings, 1 reply; 8+ messages in thread From: Drew Adams @ 2009-07-27 6:24 UTC (permalink / raw) To: 'Bastien'; +Cc: emacs-pretest-bug, 3936 > > "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? ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3936: 23.0.96; doc string of called-interactively-p 2009-07-27 6:24 ` Drew Adams @ 2009-07-27 6:43 ` Bastien 2009-07-27 8:18 ` Drew Adams 0 siblings, 1 reply; 8+ messages in thread From: Bastien @ 2009-07-27 6:43 UTC (permalink / raw) To: Drew Adams; +Cc: emacs-pretest-bug, 3936 "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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3936: 23.0.96; doc string of called-interactively-p 2009-07-27 6:43 ` Bastien @ 2009-07-27 8:18 ` Drew Adams 2009-07-27 9:17 ` Bastien 0 siblings, 1 reply; 8+ messages in thread From: Drew Adams @ 2009-07-27 8:18 UTC (permalink / raw) To: 'Bastien'; +Cc: emacs-pretest-bug, 3936 > > 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3936: 23.0.96; doc string of called-interactively-p 2009-07-27 8:18 ` Drew Adams @ 2009-07-27 9:17 ` Bastien 2009-07-27 16:04 ` Drew Adams 0 siblings, 1 reply; 8+ messages in thread From: Bastien @ 2009-07-27 9:17 UTC (permalink / raw) To: Drew Adams; +Cc: emacs-pretest-bug, 3936 "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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3936: 23.0.96; doc string of called-interactively-p 2009-07-27 9:17 ` Bastien @ 2009-07-27 16:04 ` Drew Adams 0 siblings, 0 replies; 8+ messages in thread From: Drew Adams @ 2009-07-27 16:04 UTC (permalink / raw) To: 'Bastien'; +Cc: emacs-pretest-bug, 3936 > > 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
* bug#3936: marked as done (23.0.96; doc string of called-interactively-p) 2009-07-26 20:56 ` bug#3936: 23.0.96; doc string of called-interactively-p Drew Adams 2009-07-27 2:03 ` Bastien @ 2009-08-15 22:00 ` Emacs bug Tracking System 1 sibling, 0 replies; 8+ messages in thread From: Emacs bug Tracking System @ 2009-08-15 22:00 UTC (permalink / raw) To: Chong Yidong [-- 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2009-08-15 22:00 UTC | newest] Thread overview: 8+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <877hx4n3r0.fsf@cyd.mit.edu> 2009-07-26 20:56 ` bug#3936: 23.0.96; doc string of called-interactively-p Drew Adams 2009-07-27 2:03 ` Bastien 2009-07-27 6:24 ` Drew Adams 2009-07-27 6:43 ` Bastien 2009-07-27 8:18 ` Drew Adams 2009-07-27 9:17 ` Bastien 2009-07-27 16:04 ` Drew Adams 2009-08-15 22:00 ` bug#3936: marked as done (23.0.96; doc string of called-interactively-p) Emacs bug Tracking System
Code repositories for project(s) associated with this external index https://git.savannah.gnu.org/cgit/emacs.git https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.