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

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

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