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

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

[Drew Adams]

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'

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

[Lars Ingebrigtsen]

Drew Adams <drew.adams@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

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

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

[Lars Ingebrigtsen]

Stefan Monnier <monnier@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

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

[Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors]

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

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

[Lars Ingebrigtsen]

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

Stefan Monnier <monnier@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: 


[-- Attachment #2: Type: image/png, Size: 33305 bytes --]

[-- Attachment #3: Type: text/plain, Size: 229 bytes --]


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