* Re: master 48ac40e60e: ; Fix last change. [not found] ` <20220814175134.47827C09BFD@vcs2.savannah.gnu.org> @ 2022-08-14 18:16 ` Stefan Monnier 2022-08-14 18:31 ` Eli Zaretskii 0 siblings, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2022-08-14 18:16 UTC (permalink / raw) To: Eli Zaretskii; +Cc: emacs-devel Eli Zaretskii [2022-08-14 13:51:34] wrote: > diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi > index 8c6328b440..e140998d65 100644 > --- a/doc/lispref/functions.texi > +++ b/doc/lispref/functions.texi > @@ -219,8 +219,10 @@ function. For example: > > @defun compiled-function-p object > This function returns @code{t} if @var{object} is a function object > -that was either byte-compiled (@pxref{Byte Compilation}) or > -natively-compiled (@pxref{Native Compilation}). > +that was either built-in (a.k.a.@: ``primitive'', @pxref{What is a > +Function}), or byte-compiled (@pxref{Byte Compilation}), or > +natively-compiled (@pxref{Native Compilation}), or a function loaded > +from a dynamic module (@pxref{Dynamic Modules}). > @end defun > > @defun subr-arity subr > diff --git a/etc/NEWS b/etc/NEWS > index 0788b94da2..c982684d3a 100644 > --- a/etc/NEWS > +++ b/etc/NEWS > @@ -2573,8 +2573,9 @@ patcomp.el, pc-mode.el, pc-select.el, s-region.el, and sregex.el. > > +++ > ** New function 'compiled-function-p'. > -This returns non-nil if its argument is either a byte-compiled or a > -natively-compiled function object. > +This returns non-nil if its argument is either a built-in, or a > +byte-compiled, or a natively-compiled function object, or a function > +loaded from a dynamic module. Funny: I find this rather hard to understand compared to my original wording. E.g. a reader might wonder what other cases there could be and why they don't return non-nil. IOW, I prefer an "intentional" description over the "extensional" one you installed. E.g. it's more useful when faced with a new function type. Stefan ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 18:16 ` master 48ac40e60e: ; Fix last change Stefan Monnier @ 2022-08-14 18:31 ` Eli Zaretskii 2022-08-14 18:42 ` Stefan Monnier 0 siblings, 1 reply; 12+ messages in thread From: Eli Zaretskii @ 2022-08-14 18:31 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-devel > From: Stefan Monnier <monnier@iro.umontreal.ca> > Cc: emacs-devel@gnu.org > Date: Sun, 14 Aug 2022 14:16:02 -0400 > > > +This returns non-nil if its argument is either a built-in, or a > > +byte-compiled, or a natively-compiled function object, or a function > > +loaded from a dynamic module. > > Funny: I find this rather hard to understand compared to my > original wording. E.g. a reader might wonder what other cases there > could be and why they don't return non-nil. Are there other cases? If so, what are they? If I know what they are, I can think of a better wording. But if there are no other cases, I see nothing wrong with the current wording. > IOW, I prefer an "intentional" description over the "extensional" one > you installed. The original wording was too vague. Such a specific API cannot be documented in such vague terms. > E.g. it's more useful when faced with a new function type. Whoever does that change will need to remember to update the documentation. If they don't, some future bug report will remind us. We cannot refrain from documenting useful things because we don't want to have top modify our documentation due to future changes. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 18:31 ` Eli Zaretskii @ 2022-08-14 18:42 ` Stefan Monnier 2022-08-14 18:46 ` Eli Zaretskii 0 siblings, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2022-08-14 18:42 UTC (permalink / raw) To: Eli Zaretskii; +Cc: emacs-devel Eli Zaretskii [2022-08-14 21:31:38] wrote: >> From: Stefan Monnier <monnier@iro.umontreal.ca> >> Cc: emacs-devel@gnu.org >> Date: Sun, 14 Aug 2022 14:16:02 -0400 >> >> > +This returns non-nil if its argument is either a built-in, or a >> > +byte-compiled, or a natively-compiled function object, or a function >> > +loaded from a dynamic module. >> >> Funny: I find this rather hard to understand compared to my >> original wording. E.g. a reader might wonder what other cases there >> could be and why they don't return non-nil. > Are there other cases? Obviously, there are the cases of a process, a marker, a vector, ... (and even more obviously an interpreted function), but my point is that if I imagine myself as a reader who's not knowledgeable about all those kinds of functions, I have no idea whether those 4 different cases cover "all the cases except an interpreted function". >> IOW, I prefer an "intentional" description over the "extensional" one >> you installed. > The original wording was too vague. Such a specific API cannot be > documented in such vague terms. It's not a very specific API. It's a kind of "abstract super class", so in my book it should be defined not by enumerating its current subclasses but by giving a meaningful way to decide whether a given class should be a subclass or not. Stefan ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 18:42 ` Stefan Monnier @ 2022-08-14 18:46 ` Eli Zaretskii 2022-08-14 18:56 ` Lars Ingebrigtsen 2022-08-15 2:37 ` Stefan Monnier 0 siblings, 2 replies; 12+ messages in thread From: Eli Zaretskii @ 2022-08-14 18:46 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-devel > From: Stefan Monnier <monnier@iro.umontreal.ca> > Cc: emacs-devel@gnu.org > Date: Sun, 14 Aug 2022 14:42:28 -0400 > > Eli Zaretskii [2022-08-14 21:31:38] wrote: > >> > >> Funny: I find this rather hard to understand compared to my > >> original wording. E.g. a reader might wonder what other cases there > >> could be and why they don't return non-nil. > > Are there other cases? > > Obviously, there are the cases of a process, a marker, a vector, > ... (and even more obviously an interpreted function) What do those have to do with compiled-function-p? Can a process or a marker or a vector be a compiled-function-p? > but my point is > that if I imagine myself as a reader who's not knowledgeable about all > those kinds of functions, I have no idea whether those 4 different cases > cover "all the cases except an interpreted function". That's why there are cross-references to where they are described. > It's not a very specific API. It's a kind of "abstract super class", so > in my book it should be defined not by enumerating its current > subclasses but by giving a meaningful way to decide whether a given > class should be a subclass or not. Sorry, I reject the idea that abstract classes cannot be usefully documented in concrete terms. At least there's no excuse for not trying. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 18:46 ` Eli Zaretskii @ 2022-08-14 18:56 ` Lars Ingebrigtsen 2022-08-14 19:15 ` Eli Zaretskii 2022-08-15 2:37 ` Stefan Monnier 1 sibling, 1 reply; 12+ messages in thread From: Lars Ingebrigtsen @ 2022-08-14 18:56 UTC (permalink / raw) To: Eli Zaretskii; +Cc: Stefan Monnier, emacs-devel Eli Zaretskii <eliz@gnu.org> writes: > Sorry, I reject the idea that abstract classes cannot be usefully > documented in concrete terms. At least there's no excuse for not > trying. I think it's much easier to describe what the function does in the semi-negative: The argument is a function, and it's not a lambda/closure. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 18:56 ` Lars Ingebrigtsen @ 2022-08-14 19:15 ` Eli Zaretskii 2022-08-14 19:23 ` Lars Ingebrigtsen 0 siblings, 1 reply; 12+ messages in thread From: Eli Zaretskii @ 2022-08-14 19:15 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: monnier, emacs-devel > From: Lars Ingebrigtsen <larsi@gnus.org> > Cc: Stefan Monnier <monnier@iro.umontreal.ca>, emacs-devel@gnu.org > Date: Sun, 14 Aug 2022 20:56:32 +0200 > > Eli Zaretskii <eliz@gnu.org> writes: > > > Sorry, I reject the idea that abstract classes cannot be usefully > > documented in concrete terms. At least there's no excuse for not > > trying. > > I think it's much easier to describe what the function does in the > semi-negative: The argument is a function, and it's not a > lambda/closure. It might be easier, but I personally would remain utterly confused by such a description. In general, saying what a thing is NOT is a very inefficient method of explaining what it IS, because there are so many things that are not it. What exactly is the problem with the current wording? Can you or Stefan or someone else point out the actual deficiencies (as opposed to semi-philosophical considerations)? ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 19:15 ` Eli Zaretskii @ 2022-08-14 19:23 ` Lars Ingebrigtsen 2022-08-15 2:23 ` Eli Zaretskii 0 siblings, 1 reply; 12+ messages in thread From: Lars Ingebrigtsen @ 2022-08-14 19:23 UTC (permalink / raw) To: Eli Zaretskii; +Cc: monnier, emacs-devel Eli Zaretskii <eliz@gnu.org> writes: > What exactly is the problem with the current wording? Can you or > Stefan or someone else point out the actual deficiencies (as opposed > to semi-philosophical considerations)? I thought it was clear the original way Stefan phrased it -- listing all the different types of things it can be leads me to wonder what types aren't in that list. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 19:23 ` Lars Ingebrigtsen @ 2022-08-15 2:23 ` Eli Zaretskii 2022-08-15 4:30 ` Lars Ingebrigtsen 0 siblings, 1 reply; 12+ messages in thread From: Eli Zaretskii @ 2022-08-15 2:23 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: monnier, emacs-devel > From: Lars Ingebrigtsen <larsi@gnus.org> > Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org > Date: Sun, 14 Aug 2022 21:23:54 +0200 > > Eli Zaretskii <eliz@gnu.org> writes: > > > What exactly is the problem with the current wording? Can you or > > Stefan or someone else point out the actual deficiencies (as opposed > > to semi-philosophical considerations)? > > I thought it was clear the original way Stefan phrased it -- listing all > the different types of things it can be leads me to wonder what types > aren't in that list. None. The idea was that they should all be mentioned, and the wording shouldn't leave you wondering. Which part does? ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-15 2:23 ` Eli Zaretskii @ 2022-08-15 4:30 ` Lars Ingebrigtsen 2022-08-15 11:30 ` Eli Zaretskii 0 siblings, 1 reply; 12+ messages in thread From: Lars Ingebrigtsen @ 2022-08-15 4:30 UTC (permalink / raw) To: Eli Zaretskii; +Cc: monnier, emacs-devel Eli Zaretskii <eliz@gnu.org> writes: > None. The idea was that they should all be mentioned, and the wording > shouldn't leave you wondering. Which part does? The part where you list four different function object types without mentioning how many there are. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-15 4:30 ` Lars Ingebrigtsen @ 2022-08-15 11:30 ` Eli Zaretskii 0 siblings, 0 replies; 12+ messages in thread From: Eli Zaretskii @ 2022-08-15 11:30 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: monnier, emacs-devel > From: Lars Ingebrigtsen <larsi@gnus.org> > Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org > Date: Mon, 15 Aug 2022 06:30:30 +0200 > > Eli Zaretskii <eliz@gnu.org> writes: > > > None. The idea was that they should all be mentioned, and the wording > > shouldn't leave you wondering. Which part does? > > The part where you list four different function object types without > mentioning how many there are. In general, when one lists four types and doesn't say "e.g." or "such as" or something like that, the intent is to say these four are all there is. ^ permalink raw reply [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-14 18:46 ` Eli Zaretskii 2022-08-14 18:56 ` Lars Ingebrigtsen @ 2022-08-15 2:37 ` Stefan Monnier 2022-08-15 11:20 ` Eli Zaretskii 1 sibling, 1 reply; 12+ messages in thread From: Stefan Monnier @ 2022-08-15 2:37 UTC (permalink / raw) To: Eli Zaretskii; +Cc: emacs-devel >> It's not a very specific API. It's a kind of "abstract super class", so >> in my book it should be defined not by enumerating its current >> subclasses but by giving a meaningful way to decide whether a given >> class should be a subclass or not. > Sorry, I reject the idea that abstract classes cannot be usefully > documented in concrete terms. At least there's no excuse for not > trying. I'm not opposed to doing it, but I feel that it's not sufficient because it doesn't say why that abstract class exists (i.e. what it is that makes it meaningful to group those different classes under that abstract class). To me it's akin to describing a particular image by listing the pixels it contains and their color but without saying what the image represents. We may be able to use our brain to figure out what the image represents, but it's not always obvious that everyone will end up with the same understanding. How 'bout the patch below? Stefan diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index ddf7cff6c2e..983dfe2ec59 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -219,10 +219,12 @@ What Is a Function @defun compiled-function-p object This function returns @code{t} if @var{object} is a function object -that was either built-in (a.k.a.@: ``primitive'', @pxref{What Is a -Function}), or byte-compiled (@pxref{Byte Compilation}), or -natively-compiled (@pxref{Native Compilation}), or a function loaded -from a dynamic module (@pxref{Dynamic Modules}). +that is not in the form of ELisp source code but something like +machine code or byte code instead. More specifically it returns +@code{t} if the function is built-in (a.k.a.@: ``primitive'', +@pxref{What Is a Function}), or byte-compiled (@pxref{Byte +Compilation}), or natively-compiled (@pxref{Native Compilation}), or +a function loaded from a dynamic module (@pxref{Dynamic Modules}). @end defun @defun subr-arity subr ^ permalink raw reply related [flat|nested] 12+ messages in thread
* Re: master 48ac40e60e: ; Fix last change. 2022-08-15 2:37 ` Stefan Monnier @ 2022-08-15 11:20 ` Eli Zaretskii 0 siblings, 0 replies; 12+ messages in thread From: Eli Zaretskii @ 2022-08-15 11:20 UTC (permalink / raw) To: Stefan Monnier; +Cc: emacs-devel > From: Stefan Monnier <monnier@iro.umontreal.ca> > Cc: emacs-devel@gnu.org > Date: Sun, 14 Aug 2022 22:37:10 -0400 > > > Sorry, I reject the idea that abstract classes cannot be usefully > > documented in concrete terms. At least there's no excuse for not > > trying. > > I'm not opposed to doing it, but I feel that it's not sufficient because > it doesn't say why that abstract class exists (i.e. what it is that > makes it meaningful to group those different classes under that abstract > class). I have nothing against adding something along those lines. > How 'bout the patch below? Fine with me, thanks. ^ permalink raw reply [flat|nested] 12+ messages in thread
end of thread, other threads:[~2022-08-15 11:30 UTC | newest] Thread overview: 12+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <166049949398.16955.13217655219158269477@vcs2.savannah.gnu.org> [not found] ` <20220814175134.47827C09BFD@vcs2.savannah.gnu.org> 2022-08-14 18:16 ` master 48ac40e60e: ; Fix last change Stefan Monnier 2022-08-14 18:31 ` Eli Zaretskii 2022-08-14 18:42 ` Stefan Monnier 2022-08-14 18:46 ` Eli Zaretskii 2022-08-14 18:56 ` Lars Ingebrigtsen 2022-08-14 19:15 ` Eli Zaretskii 2022-08-14 19:23 ` Lars Ingebrigtsen 2022-08-15 2:23 ` Eli Zaretskii 2022-08-15 4:30 ` Lars Ingebrigtsen 2022-08-15 11:30 ` Eli Zaretskii 2022-08-15 2:37 ` Stefan Monnier 2022-08-15 11:20 ` Eli Zaretskii
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.