bug#13572: 24.3.50; `describe-function' -> "This function has a compiler macro..."

bug#13572: 24.3.50; `describe-function' -> "This function has a compiler macro..."

[Drew Adams]

C-h f registerv-p
 
The help says only this:
 
  This function has a compiler macro in `register.el'.
 
This help is not very helpful.  I, for one, do not understand it.
 
Searching `register.el' does not turn up any definition of
`registerv-p', that I can find.  There are only invocations of the
function in that file.
 
And searching the Elisp manual for "compiler macro" turns up nothing.
Perhaps this concept needs to be documented.
 
Digging into help-fns.el I find that the test that produces this helpful
message is (get function 'compiler-macro-file).  But I haven't tried to
search further to see what can be understood about this.
 
Please document all of the constructs that you use in the Emacs source
code, including this one.
 
In GNU Emacs 24.3.50.1 (i386-mingw-nt5.1.2600)
 of 2013-01-25 on ODIEONE
Bzr revision: 111604 eliz@gnu.org-20130125143821-1ykj7ia1qjojjjnp
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -IC:/Devel/emacs/build/include --ldflags -LC:/Devel/emacs/build/lib'
 

bug#13572: 24.3.50; `describe-function' -> "This function has a compiler macro..."

[Drew Adams]

Digging further (thanks to the doc string for `register-alist', and with prior
knowledge of defstruct), I figured out that this is a type predicate constructed
automatically for a register defstruct.

The doc needs to be improved for this kind of thing (automatically generated
functions).  If you are going to add and use things like `defstruct', then
please do it right.  Emacs dev should not just be creating functions that have
no doc willy nilly.

bug#13572: 24.3.50; `describe-function' -> "This function has a compiler macro..."

[Drew Adams]

> this is a type predicate constructed
> automatically for a register defstruct.
> 
> The doc needs to be improved for this kind of thing 
> (automatically generated functions).

I guess Common Lisp defstruct does not allow for a doc string for the generated
predicate (unlike the case for slots, constructor functions, and the defstruct
itself).

It would be good if Emacs Lisp could automatically generate a minimal doc string
for the predicate that at least referred to the structure.  Something like this:

 "Type predicate for a NAME structure."

where NAME is the defstruct name.

I guess that would be a wishlist item, since this is not part of the CL spec.

Apart from that, in this particular defstruct it would be good to at least add
doc strings for those things that allow it.  A doc string for the defstruct
itself is the least users could ask for.

bug#13572: 24.3.50; `describe-function' -> "This function has a compiler macro..."

[Jambunathan K]

"Drew Adams" <drew.adams@oracle.com> writes:

>> this is a type predicate constructed
>> automatically for a register defstruct.
>> 
>> The doc needs to be improved for this kind of thing 
>> (automatically generated functions).
>
> I guess Common Lisp defstruct does not allow for a doc string for the generated
> predicate (unlike the case for slots, constructor functions, and the defstruct
> itself).
>
> It would be good if Emacs Lisp could automatically generate a minimal doc string
> for the predicate that at least referred to the structure.  Something like this:
>
>  "Type predicate for a NAME structure."
>
> where NAME is the defstruct name.
>
> I guess that would be a wishlist item, since this is not part of the CL spec.
>
> Apart from that, in this particular defstruct it would be good to at least add
> doc strings for those things that allow it.  A doc string for the defstruct
> itself is the least users could ask for.

+1

I ran in to the some confusion while looking at compile.el - constructs
like `compilation--message->loc' which are reported as compiler macros
(Part of the confusion may be because of my ignorance.  Only "macros"
that I know of is `defmacros')

,----
| (cl-defstruct (compilation--message
|             (:constructor nil)
|             (:copier nil)
|             ;; (:type list)                ;Old representation.
|             (:constructor compilation--make-message (loc type end-loc))
|             (:conc-name compilation--message->))
|   loc type end-loc)
`----

Enhanced docstring can educate ignorant people like me...
--