GNU bug report logs - #23264
25.0.90; `C-h f' (`describe-function'): "This function has a compiler macro"

Previous Next

Package: emacs;

Reported by: Drew Adams <drew.adams <at> oracle.com>

Date: Sun, 10 Apr 2016 18:49:02 UTC

Severity: wishlist

Tags: moreinfo

Found in version 25.0.90

Fixed in version 29.1

Done: Lars Ingebrigtsen <larsi <at> gnus.org>

Bug is archived. No further changes may be made.

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 23264 in the body.
You can then email your comments to 23264 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

View this report as an mbox folder, status mbox, maintainer mbox


Report forwarded to bug-gnu-emacs <at> gnu.org:
bug#23264; Package emacs. (Sun, 10 Apr 2016 18:49:02 GMT) Full text and rfc822 format available.

Acknowledgement sent to Drew Adams <drew.adams <at> oracle.com>:
New bug report received and forwarded. Copy sent to bug-gnu-emacs <at> gnu.org. (Sun, 10 Apr 2016 18:49:02 GMT) Full text and rfc822 format available.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.90; `C-h f' (`describe-function'): "This function has a compiler
 macro"
Date: Sun, 10 Apr 2016 11:47:57 -0700 (PDT)
This mystery sentence was added to the output of
`describe-function' - at the very top, no less:

  This function has a compiler macro.

I had to search the _source code_ to find out what that is
meant to mean - what it means for a function to have a
"compiler macro", and even what a "compiler macro" is.

And having found symbol property `compiler-macro' used in
the source code, I had to then search the Elisp manual for
that (there is no index entry for it).  Finally, I found a
little light in node `Declare Form'.

It cannot be clear to readers of `C-h f eval-after-load'
(for example) what that mystery sentence is for.  If we are
going to include mention of this we should use English to
get across the real point, which is presumably to say that a
call to the function might be expanded by the compiler in
different ways.

I admit that I still do not understand why we would tell
users this in `C-h f' output.  And perhaps I still do not
fully grasp the message.

What seems clear to me is that most users will have NO CLUE
what this mystery sentence (again, at the top of the help
output, no less) is trying to tell them, much less why it is
(or isn't) important.


In GNU Emacs 25.0.90.4 (i686-w64-mingw32)
 of 2016-03-20
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --host=i686-w64-mingw32 --without-dbus
 --without-compress-install CFLAGS=-static'




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#23264; Package emacs. (Fri, 13 May 2022 13:02:01 GMT) Full text and rfc822 format available.

Message #8 received at 23264 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 23264 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
 Stefan Monnier <monnier <at> iro.umontreal.ca>
Subject: Re: bug#23264: 25.0.90; `C-h f' (`describe-function'): "This
 function has a compiler macro"
Date: Fri, 13 May 2022 15:00:56 +0200
Drew Adams <drew.adams <at> oracle.com> writes:

> This mystery sentence was added to the output of
> `describe-function' - at the very top, no less:
>
>   This function has a compiler macro.

[...]

> I admit that I still do not understand why we would tell
> users this in `C-h f' output.  And perhaps I still do not
> fully grasp the message.

It doesn't seem very useful to me either, no -- it doesn't really convey
much of interest to the user.  Eli, Stefan -- what do you think?  Should
we just remove it?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no




Added tag(s) moreinfo. Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Fri, 13 May 2022 13:02:01 GMT) Full text and rfc822 format available.

Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#23264; Package emacs. (Fri, 13 May 2022 14:21:02 GMT) Full text and rfc822 format available.

Message #13 received at 23264 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 23264 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#23264: 25.0.90; `C-h f' (`describe-function'): "This
 function has a compiler macro"
Date: Fri, 13 May 2022 10:20:17 -0400
>>   This function has a compiler macro.
[...]
> It doesn't seem very useful to me either, no -- it doesn't really convey
> much of interest to the user.  Eli, Stefan -- what do you think?  Should
> we just remove it?

I can see to benefits:

1- If it includes a link to the compiler macro.  Admittedly, compiler
   macros are supposed to be placed directly inside the `declare` of the
   function, so you can get there via the usual link to the function's
   definition, which makes this link's usefulness rather marginal.
   (except in theory for those rare exceptions where the compiler macro
   is not provided via `declare`, but to be honest, I can't think of any
   and `grep` couldn't find any either).
2- It warns that advice and (more generally) redefinitions of this
   function may not be obeys at all call sites.

Point 1 is quite weak.
Point 2 is a bit more interesting but then we should say so more
explicitly and (more importantly) we should also say so for those
functions which have the same property but for other reasons (e.g. they
have their own byte-code, or they have a `byte-compile` or
`byte-optimizer` property).

IOW, I agree but maybe it would be a good idea to replace it with
a better message that covers this and similar cases warning about
applicability of `advice`.


        Stefan





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#23264; Package emacs. (Fri, 13 May 2022 16:00:02 GMT) Full text and rfc822 format available.

Message #16 received at 23264 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 23264 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#23264: 25.0.90; `C-h f' (`describe-function'): "This
 function has a compiler macro"
Date: Fri, 13 May 2022 17:59:13 +0200
Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> 1- If it includes a link to the compiler macro.  Admittedly, compiler
>    macros are supposed to be placed directly inside the `declare` of the
>    function, so you can get there via the usual link to the function's
>    definition, which makes this link's usefulness rather marginal.
>    (except in theory for those rare exceptions where the compiler macro
>    is not provided via `declare`, but to be honest, I can't think of any
>    and `grep` couldn't find any either).

There's this:

(put 'featurep 'compiler-macro
     (lambda (form feature &rest _ignore)
       ;; Emacs-21's byte-code doesn't run under XEmacs or SXEmacs anyway, so
       ;; we can safely optimize away this test.
       (if (member feature '('xemacs 'sxemacs 'emacs))
           (eval form)
         form)))

But that's not a symbol, so Emacs won't offer up a button for it.  But
it is indeed extremely rare.

> 2- It warns that advice and (more generally) redefinitions of this
>    function may not be obeys at all call sites.

Hm, yes, that can be handy to know.

> Point 1 is quite weak.
> Point 2 is a bit more interesting but then we should say so more
> explicitly and (more importantly) we should also say so for those
> functions which have the same property but for other reasons (e.g. they
> have their own byte-code, or they have a `byte-compile` or
> `byte-optimizer` property).
>
> IOW, I agree but maybe it would be a good idea to replace it with
> a better message that covers this and similar cases warning about
> applicability of `advice`.

Do you have any suggested text?  🙃

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no




Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#23264; Package emacs. (Fri, 13 May 2022 17:51:02 GMT) Full text and rfc822 format available.

Message #19 received at 23264 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 23264 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#23264: 25.0.90; `C-h f' (`describe-function'): "This
 function has a compiler macro"
Date: Fri, 13 May 2022 13:49:51 -0400
>> IOW, I agree but maybe it would be a good idea to replace it with
>> a better message that covers this and similar cases warning about
>> applicability of `advice`.
> Do you have any suggested text?  🙃

I heard Lars had a good one, why don't you ask him?


        Stefan





Information forwarded to bug-gnu-emacs <at> gnu.org:
bug#23264; Package emacs. (Sat, 14 May 2022 02:10:02 GMT) Full text and rfc822 format available.

Message #22 received at 23264 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: 23264 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
 Drew Adams <drew.adams <at> oracle.com>
Subject: Re: bug#23264: 25.0.90; `C-h f' (`describe-function'): "This
 function has a compiler macro"
Date: Sat, 14 May 2022 04:09:11 +0200
[Message part 1 (text/plain, inline)]
Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> I heard Lars had a good one, why don't you ask him?

Darn.

I've now added a short node to the manual and adjusted the output in
help-fns--compiler-macro to also peek at the other two byte compilation
things: 

[Message part 2 (image/png, inline)]
[Message part 3 (text/plain, inline)]
Feel free to adjust the manual node -- it's pretty terse, and should
probably be expanded a bit, but I'm not sure how much.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug marked as fixed in version 29.1, send any further explanations to 23264 <at> debbugs.gnu.org and Drew Adams <drew.adams <at> oracle.com> Request was from Lars Ingebrigtsen <larsi <at> gnus.org> to control <at> debbugs.gnu.org. (Sat, 14 May 2022 02:10:02 GMT) Full text and rfc822 format available.

bug archived. Request was from Debbugs Internal Request <help-debbugs <at> gnu.org> to internal_control <at> debbugs.gnu.org. (Sat, 11 Jun 2022 11:24:06 GMT) Full text and rfc822 format available.

This bug report was last modified 1 year and 291 days ago.

Previous Next


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