* bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"
@ 2019-07-02 18:05 Drew Adams
2019-07-02 19:41 ` Eli Zaretskii
` (2 more replies)
0 siblings, 3 replies; 6+ messages in thread
From: Drew Adams @ 2019-07-02 18:05 UTC (permalink / raw)
To: 36478
`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''
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"
2019-07-02 18:05 bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Drew Adams
@ 2019-07-02 19:41 ` Eli Zaretskii
2019-07-04 1:34 ` Richard Stallman
2022-02-02 18:55 ` Lars Ingebrigtsen
2 siblings, 0 replies; 6+ messages in thread
From: Eli Zaretskii @ 2019-07-02 19:41 UTC (permalink / raw)
To: Drew Adams; +Cc: 36478
> Date: Tue, 2 Jul 2019 11:05:18 -0700 (PDT)
> From: Drew Adams <drew.adams@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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"
[not found] ` <<83r278cjho.fsf@gnu.org>
@ 2019-07-02 20:13 ` Drew Adams
2019-07-04 1:35 ` Richard Stallman
0 siblings, 1 reply; 6+ messages in thread
From: Drew Adams @ 2019-07-02 20:13 UTC (permalink / raw)
To: Eli Zaretskii, Drew Adams; +Cc: 36478
> > 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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"
2019-07-02 18:05 bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Drew Adams
2019-07-02 19:41 ` Eli Zaretskii
@ 2019-07-04 1:34 ` Richard Stallman
2022-02-02 18:55 ` Lars Ingebrigtsen
2 siblings, 0 replies; 6+ messages in thread
From: Richard Stallman @ 2019-07-04 1:34 UTC (permalink / raw)
To: Drew Adams; +Cc: 36478
[[[ 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)
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"
2019-07-02 20:13 ` Drew Adams
@ 2019-07-04 1:35 ` Richard Stallman
0 siblings, 0 replies; 6+ messages in thread
From: Richard Stallman @ 2019-07-04 1:35 UTC (permalink / raw)
To: Drew Adams; +Cc: 36478
[[[ 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)
^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"
2019-07-02 18:05 bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Drew Adams
2019-07-02 19:41 ` Eli Zaretskii
2019-07-04 1:34 ` Richard Stallman
@ 2022-02-02 18:55 ` Lars Ingebrigtsen
2 siblings, 0 replies; 6+ messages in thread
From: Lars Ingebrigtsen @ 2022-02-02 18:55 UTC (permalink / raw)
To: Drew Adams; +Cc: 36478
Drew Adams <drew.adams@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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2022-02-02 18:55 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-07-02 18:05 bug#36478: 26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state" Drew Adams
2019-07-02 19:41 ` Eli Zaretskii
2019-07-04 1:34 ` Richard Stallman
2022-02-02 18:55 ` Lars Ingebrigtsen
[not found] <<13f5f7df-9017-45a0-986f-8b1a4ee0e9bd@default>
[not found] ` <<83r278cjho.fsf@gnu.org>
2019-07-02 20:13 ` Drew Adams
2019-07-04 1:35 ` Richard Stallman
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).