Re: master 48ac40e60e: ; Fix last change.

Re: master 48ac40e60e: ; Fix last change.

[Stefan Monnier]

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

Re: master 48ac40e60e: ; Fix last change.

[Eli Zaretskii]

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

Re: master 48ac40e60e: ; Fix last change.

[Stefan Monnier]

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

Re: master 48ac40e60e: ; Fix last change.

[Eli Zaretskii]

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

Re: master 48ac40e60e: ; Fix last change.

[Lars Ingebrigtsen]

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.

Re: master 48ac40e60e: ; Fix last change.

[Eli Zaretskii]

> 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)?

Re: master 48ac40e60e: ; Fix last change.

[Lars Ingebrigtsen]

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.

Re: master 48ac40e60e: ; Fix last change.

[Eli Zaretskii]

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

Re: master 48ac40e60e: ; Fix last change.

[Stefan Monnier]

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

Re: master 48ac40e60e: ; Fix last change.

[Lars Ingebrigtsen]

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.

Re: master 48ac40e60e: ; Fix last change.

[Eli Zaretskii]

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

Re: master 48ac40e60e: ; Fix last change.

[Eli Zaretskii]

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