GNU bug report logs - #36478
26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"

Previous Next

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

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

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: 26.2; Doc strings with "This function has a compiler macro..." and
 "This function does not change global state"
Date: Tue, 2 Jul 2019 11:05:18 -0700 (PDT)

`C-h f zerop' tells you this:

 zerop is a compiled Lisp function in 'subr.el'.

 (zerop NUMBER)

 This function has a compiler macro 'zerop--anon-cmacro'.

 Return t if NUMBER is zero.
 This function does not change global state, including the match data.

Why on earth would we put that info about the function having a compiler
macro before the first doc string line?

What does it even mean?  Searching for "compiler macro" in the Elisp
manual I find mention of it (in passing only) in node `Defining
Functions', but no definition of it.  And there's no index entry for it,
AFAICT.  Reading that node, I still don't know what "compiler macro"
really means.  Perhaps it means code that inlines a function definition
at byte-compilation time?

That whole node `Defining Functions' is pretty much incomprehensible
now, with the additions about ...inline....  Compare node `Inline
Functions', which is quite clear.

For example:

  Functions defined via 'define-inline' have several advantages with
  respect to macros defined by 'defsubst' or 'defmacro'...

Huh? `defsubst' defines macros?  I don't think so.

I think a node should probably be dedicated to `define-inline' or to
whatever it does.  The concepts really need to be developed.  Putting
this, whatever it is, in with `defun' in the main node about defining
functions does users, especially newbies, a disservice.

The help for a function (e.g. `zerop') should, after showing the
signature, start with the doc string, which says what the function does.
The help should not start by providing peripheral info about the
function.  Putting this info first doesn't follow Emacs longstanding
help convention.

Not to mention that if you click that `zerop--anon-cmacro' link you get
this:

 zerop--anon-cmacro is a compiled Lisp function in 'subr.el'.

 (zerop--anon-cmacro _ NUMBER)

 Not documented.

What's more: if you click the `subr.el' link you get nowhere that tells
you anything about `zerop--anon-cmacro' - there are no occurrences of
`zerop--anon-cmacro' in that file.

Wunderbar.  Thanks for the help, Emacs!

This is a real mess - doesn't help users.  Instead, it gets in their
way.  Please DTRT.  Either get rid of such obscurantism or put it at the
end of the `C-h f' output and fix its useless links.

---

In addition, why do we automatically add the following sentence to the
help (without even an intervening blank line), as if it were the second
doc-string line:

 This function does not change global state, including the match data.

Who asked for that?  Which functions get that added to their doc
strings?  Every function for which that's true?  I doubt that, and if
I'm right then the fact that some functions do get that added is
misleading.


In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 36478 <at> debbugs.gnu.org
Subject: Re: bug#36478: 26.2;
 Doc strings with "This function has a compiler macro..." and "This
 function does not change global state"
Date: Tue, 02 Jul 2019 22:41:07 +0300

> Date: Tue, 2 Jul 2019 11:05:18 -0700 (PDT)
> From: Drew Adams <drew.adams <at> oracle.com>
> 
> `C-h f zerop' tells you this:
> 
>  zerop is a compiled Lisp function in 'subr.el'.
> 
>  (zerop NUMBER)
> 
>  This function has a compiler macro 'zerop--anon-cmacro'.
> 
>  Return t if NUMBER is zero.
>  This function does not change global state, including the match data.
> 
> Why on earth would we put that info about the function having a compiler
> macro before the first doc string line?

The parts that got you so worked up are generated automatically.

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 36478 <at> debbugs.gnu.org
Subject: RE: bug#36478: 26.2; Doc strings with "This function has a compiler
 macro..." and "This function does not change global state"
Date: Tue, 2 Jul 2019 13:13:40 -0700 (PDT)

> > Why on earth would we put that info about the function having a compiler
> > macro before the first doc string line?
> 
> The parts that got you so worked up are generated automatically.

Yes, obviously; I realize that.  "We" (someone)
created and added the code that does that.  And "we"
(someone) added the descriptions of `define-inline'
etc. to the manual.  However "automatic", none of
this fell from the sky.

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

From: Richard Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 36478 <at> debbugs.gnu.org
Subject: Re: bug#36478: 26.2;
 Doc strings with "This function has a compiler macro..." and "This
 function does not change global state"
Date: Wed, 03 Jul 2019 21:34:11 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

   > zerop is a compiled Lisp function in 'subr.el'.

   > (zerop NUMBER)

   > This function has a compiler macro 'zerop--anon-cmacro'.

   > Return t if NUMBER is zero.
   > This function does not change global state, including the match data.

The "compiler macro" line is useful for people debugging compilation,
but for Lisp programmers in general it is only clutter.

How about replacing that line with the text "(+ compiler macro)"
after "compiled Lisp function"?

That way it will still be easy to see when you're debugging
compilation, but the amount of clutter for everyone else will be less.


-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

From: Richard Stallman <rms <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: eliz <at> gnu.org, 36478 <at> debbugs.gnu.org, drew.adams <at> oracle.com
Subject: Re: bug#36478: 26.2;
 Doc strings with "This function has a compiler macro..." and "This
 function does not change global state"
Date: Wed, 03 Jul 2019 21:35:16 -0400

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Yes, obviously; I realize that.  "We" (someone)
  > created and added the code that does that.  And "we"
  > (someone) added the descriptions of `define-inline'
  > etc. to the manual.  However "automatic", none of
  > this fell from the sky.

I agree with your point, but that is a harsh way to put it.  Would you
please make an effort to express your points in a kind way?  See
https://gnu.org/philosophy/kind-communication.html.

In addition to helping people generally feel better,
it could predispose others to be more receptive to your
substantial points.

-- 
Dr Richard Stallman
President, Free Software Foundation (https://gnu.org, https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: Re: Perhaps rearrange *Help* buffer a bit?
Date: Mon, 08 Jul 2019 17:14:05 -0400

> I think Drew (or somebody?) mentioned this in a bug report the other
> day: The way the automated stuff is arranged in the *Help* buffer is
> perhaps not optimal.

>   This function has a compiler macro ‘internal--compiler-macro-cXXr’.
>   Probably introduced at or before Emacs version 20.
[...]
>   Probably introduced at or before Emacs version 1.2.
>   This function does not change global state, including the match data.
[...]
> So the thought here is that those indented lines isn't what's most
> interesting to the user.

I recently reworked the generation of this text specifically to try and
make it easier to tweak it.

> Anyway, what about rearranging this a bit so that the stuff the users
> are interested in comes first?
[...]
> Let the bike-shedding commence!

Here's my favorite color: 
- don't move it to the end, because it's much too far.
- hide it by default, with some obvious-enough button-like thingy to
  expand it on demand.
- maybe the first line could also be moved into this "metadata" block.
- These *Help* buffers would benefit from a bit of face-lift (e.g. put
  a different face on the metadata part, yet another on the
  calling-convention example, ...).


        Stefan

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: Re: Perhaps rearrange *Help* buffer a bit?
Date: Tue, 09 Jul 2019 00:26:29 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> Here's my favorite color: 
> - don't move it to the end, because it's much too far.
> - hide it by default, with some obvious-enough button-like thingy to
>   expand it on demand.
> - maybe the first line could also be moved into this "metadata" block.

A button that says "Technical details..." or something?  Or... a
text-less button would perhaps be better.

To take the `car' example again:

---
(car LIST) ...

Return the car of LIST.  If arg is nil, return nil.
Error if arg is not nil and not a cons cell.  See also ‘car-safe’.

See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
Lisp concepts such as car, cdr, cons cell and list.
---

The "..." after the function call signature could be marked in the link
face, and could expand into:

---
  car is a built-in function in ‘C source code’.
  Probably introduced at or before Emacs version 1.2.
  This function does not change global state, including the match data.
---

And `car' in the signature could be a link to the source code, as the
"C source code" is now, so you don't have to expand the details to get
to the link.

> - These *Help* buffers would benefit from a bit of face-lift (e.g. put
>   a different face on the metadata part, yet another on the
>   calling-convention example, ...).

The parameters are in an italic face...  If we're hiding the details,
perhaps a special face for the details isn't necessary?

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Stefan Monnier
 <monnier <at> iro.umontreal.ca>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: RE: bug#36478: Perhaps rearrange *Help* buffer a bit?
Date: Mon, 8 Jul 2019 16:21:52 -0700 (PDT)

> > Here's my favorite color:
> > - don't move it to the end, because it's much too far.
> > - hide it by default, with some obvious-enough button-like thingy to
> >   expand it on demand.
> > - maybe the first line could also be moved into this "metadata" block.
> 
> A button that says "Technical details..." or something?  Or... a
> text-less button would perhaps be better.

FWIW, I think I disagree with handling all such
"metadata" equally, e.g. hiding it all by default.

To me, it makes sense to show, without fishing, that
a function is autoloaded (e.g. not yet loaded),
compiled, etc.; and to show its definition location,
with a link to it; and to show a link to its advice
- especially if the advice changes the doc (which is
what the help is mainly for); and to show a variable's
value.

Such things are helpful for most users, I think, and
they're not in the way.  Such things are not so
concerned with "our" implementation details as they
are with the definition - what the thing is/does.

This is a bit like using `C-u C-x ='.  Both kinds
of help can and do show lots of information.  And
it's not good to overwhelm users at the outset with
too much info, especially in a not-very-organized
way.

But I think that for `*Help*' the info we've long
shown is pretty much user-oriented.  It's more a
question of organization.  I objected, in bug
#36478, to sticking the following kind of info
near the top, before even the first line of the
doc string:

 This function has a compiler macro 'zerop--anon-cmacro'.

Dunno how useful that info is, but a priori that's
not the place to stick it, IMO.  

Many users (I'm one) have no clue what a "compiler
macro" is or why they should care.  (And it's not
explained in the manual, which is a big part of
what bug bu#36478g is about.)

But if that info is actually useful for users (I'm
ignorant, so can't judge that) and if it were put
at or near the end of `*Help*' (and if "compiler
macro" got documented, and especially if those
words linked to the place in the manual where that's
documented), then I'd have no problem with it.

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

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: Re: Perhaps rearrange *Help* buffer a bit?
Date: Mon, 08 Jul 2019 19:30:21 -0400

> To take the `car' example again:
>
> ---
> (car LIST) ...
>
> Return the car of LIST.  If arg is nil, return nil.
> Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
>
> See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
> Lisp concepts such as car, cdr, cons cell and list.
> ---

Sounds about right, yes.  I think I'd vote to keep the function/macro
distinction displayed by default at least (and maybe function/command as
well).  Maybe simply as

    Function: (car LIST) ...
    
    Return the car of LIST.  If arg is nil, return nil.
    Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
    
    See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
    Lisp concepts such as car, cdr, cons cell and list.

> And `car' in the signature could be a link to the source code, as the
> "C source code" is now, so you don't have to expand the details to get
> to the link.

Sounds good.

>> - These *Help* buffers would benefit from a bit of face-lift (e.g. put
>>   a different face on the metadata part, yet another on the
>>   calling-convention example, ...).
> The parameters are in an italic face...  If we're hiding the details,
> perhaps a special face for the details isn't necessary?

Maybe you're right.  Then again, I think it's worth keeping the block
highlighted somehow to clearly indicate the difference between the
docstring and the auto-generated metadata, maybe with a discreet
background color.


        Stefan

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: 36478 <at> debbugs.gnu.org
Subject: Re: bug#36478: 26.2; Doc strings with "This function has a compiler
 macro..." and "This function does not change global state"
Date: Wed, 02 Feb 2022 19:55:47 +0100

Drew Adams <drew.adams <at> oracle.com> writes:

> `C-h f zerop' tells you this:
>
>  zerop is a compiled Lisp function in 'subr.el'.
>
>  (zerop NUMBER)
>
>  This function has a compiler macro 'zerop--anon-cmacro'.
>
>  Return t if NUMBER is zero.
>  This function does not change global state, including the match data.
>
> Why on earth would we put that info about the function having a compiler
> macro before the first doc string line?

In Emacs 29 these details have been moved to the end of the help buffer.

I've now also added some indexing to the manual so that it's easier to
find out what a "compiler macro" is.

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

Previous Next

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