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

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 13572 in the body.
You can then email your comments to 13572 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: 24.3.50;
	`describe-function' -> "This function has a compiler macro..."
Date: Sun, 27 Jan 2013 18:39:10 -0800

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

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <13572 <at> debbugs.gnu.org>
Subject: RE: bug#13572: 24.3.50;
	`describe-function' -> "This function has a compiler macro..."
Date: Sun, 27 Jan 2013 18:44:24 -0800

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.

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

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <13572 <at> debbugs.gnu.org>
Subject: RE: bug#13572: 24.3.50;
	`describe-function' -> "This function has a compiler macro..."
Date: Sun, 27 Jan 2013 22:26:13 -0800

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

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

From: Jambunathan K <kjambunathan <at> gmail.com>
To: "Drew Adams" <drew.adams <at> oracle.com>
Cc: 13572 <at> debbugs.gnu.org
Subject: Re: bug#13572: 24.3.50;
	`describe-function' -> "This function has a compiler macro..."
Date: Mon, 28 Jan 2013 13:38:55 +0530

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

Previous Next

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