GNU bug report logs - #28557
26.0.60; Bugs using (:documentation FORM) in closures

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 28557 in the body.
You can then email your comments to 28557 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: Gemini Lasswell <gazally <at> runbox.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Fri, 22 Sep 2017 10:30:11 -0700

[Message part 1 (text/plain, inline)]

Since Emacs 25, docstrings can be constructed using
(:documentation FORM) in closures, when lexical-binding is on. This
isn't documented except in NEWS. Bug #24773 is about Edebug specs
which have not been updated to recognize :documentation. I'd like to
fix it, so I started trying to figure out which macros accept
:documentation forms so I would know which Edebug specs to update, and
that effort turned into a collection of tests for the feature, see
attached:

[cconv-tests.el (text/plain, attachment)]

[Message part 3 (text/plain, inline)]

While doing this I found these bugs:

1. A lambda wrapped by cl-function with a :documentation form will
not get a docstring and the :documentation form will be left in the
body of the closure.

2. In code run interactively, a :documentation form in cl-defmacro or
defmacro will work correctly. However if you byte-compile that code,
the byte-compiler stops with the following error message:
    Symbol’s function definition is void: internal-make-closure

3. A :documentation form in cl-defgeneric only works if its argument
is a string literal. In cl-defmethod, it works whether the argument is
a string literal or an expression.

4. A :documentation form works in cl-iter-defun and iter-defun, but
not in iter-lambda.

Stefan, here's a list of macros in which it appears to me that
(:documentation FORM) is supposed to work. Is this correct? Am I
missing any?

lambda
pcase-lambda
defun
defmacro
cl-defun
cl-defmacro
iter-defun
cl-iter-defun
iter-lambda
function
cl-function
cl-defgeneric
cl-defmethod
defsubst
cl-defsubst

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Gemini Lasswell <gazally <at> runbox.com>
Cc: 28557 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> IRO.UMontreal.CA>
Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Sun, 03 May 2020 03:32:50 +0200

Gemini Lasswell <gazally <at> runbox.com> writes:

> Since Emacs 25, docstrings can be constructed using
> (:documentation FORM) in closures, when lexical-binding is on. This
> isn't documented except in NEWS. Bug #24773 is about Edebug specs
> which have not been updated to recognize :documentation. I'd like to
> fix it, so I started trying to figure out which macros accept
> :documentation forms so I would know which Edebug specs to update, and
> that effort turned into a collection of tests for the feature, see
> attached:

There is a long list of tests here, but it seems like none of this was
ever committed to master.  Should it be?

> While doing this I found these bugs:
>
> 1. A lambda wrapped by cl-function with a :documentation form will
> not get a docstring and the :documentation form will be left in the
> body of the closure.
>
> 2. In code run interactively, a :documentation form in cl-defmacro or
> defmacro will work correctly. However if you byte-compile that code,
> the byte-compiler stops with the following error message:
>     Symbol’s function definition is void: internal-make-closure
>
> 3. A :documentation form in cl-defgeneric only works if its argument
> is a string literal. In cl-defmethod, it works whether the argument is
> a string literal or an expression.
>
> 4. A :documentation form works in cl-iter-defun and iter-defun, but
> not in iter-lambda.
>
> Stefan, here's a list of macros in which it appears to me that
> (:documentation FORM) is supposed to work. Is this correct? Am I
> missing any?
>
> lambda
> pcase-lambda
> defun
> defmacro
> cl-defun
> cl-defmacro
> iter-defun
> cl-iter-defun
> iter-lambda
> function
> cl-function
> cl-defgeneric
> cl-defmethod
> defsubst
> cl-defsubst

Does anyone know the answers to the above questions?

Best regards,
Stefan Kangas

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 28557 <at> debbugs.gnu.org, gazally <at> runbox.com, monnier <at> IRO.UMontreal.CA
Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Sun, 03 May 2020 17:52:39 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Date: Sun, 03 May 2020 03:32:50 +0200
> Cc: 28557 <at> debbugs.gnu.org, Stefan Monnier <monnier <at> IRO.UMontreal.CA>
> 
> There is a long list of tests here, but it seems like none of this was
> ever committed to master.  Should it be?

Why not?  Tests are always good and can never break anything in Emacs.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 28557 <at> debbugs.gnu.org, gazally <at> runbox.com, monnier <at> IRO.UMontreal.CA
Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Sun, 03 May 2020 21:22:58 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> gnu.org> writes:

>> There is a long list of tests here, but it seems like none of this was
>> ever committed to master.  Should it be?
>
> Why not?  Tests are always good and can never break anything in Emacs.

OK.  However, we only got a .el file by Gemini Lasswell, not a patch.

Is there any reason not to commit this in his name like in the
attached patch?

I have made only very minor changes in the attached patch to mark
three tests as ':expected-result :failed' and comment out the two
tests where the byte-compiler fails.  I also wrote a ChangeLog entry.

Thanks.

Best regards,
Stefan Kangas

[0001-Add-new-cconv-tests-Bug-28557.patch (text/x-diff, attachment)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 28557 <at> debbugs.gnu.org, gazally <at> runbox.com, monnier <at> IRO.UMontreal.CA
Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Mon, 04 May 2020 16:47:45 +0300

> From: Stefan Kangas <stefan <at> marxist.se>
> Cc: 28557 <at> debbugs.gnu.org,  gazally <at> runbox.com,  monnier <at> IRO.UMontreal.CA
> Date: Sun, 03 May 2020 21:22:58 +0200
> 
> > Why not?  Tests are always good and can never break anything in Emacs.
> 
> OK.  However, we only got a .el file by Gemini Lasswell, not a patch.
> 
> Is there any reason not to commit this in his name like in the
> attached patch?

I don't see why not, provided that Gemini Lasswell agrees.

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

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 28557 <at> debbugs.gnu.org, gazally <at> runbox.com, monnier <at> iro.umontreal.ca
Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Tue, 4 Aug 2020 10:06:46 -0700

Eli Zaretskii <eliz <at> gnu.org> writes:

>> From: Stefan Kangas <stefan <at> marxist.se>
>> Cc: 28557 <at> debbugs.gnu.org,  gazally <at> runbox.com,  monnier <at> IRO.UMontreal.CA
>> Date: Sun, 03 May 2020 21:22:58 +0200
>>
>> > Why not?  Tests are always good and can never break anything in Emacs.
>>
>> OK.  However, we only got a .el file by Gemini Lasswell, not a patch.
>>
>> Is there any reason not to commit this in his name like in the
>> attached patch?
>
> I don't see why not, provided that Gemini Lasswell agrees.

No reply within 13 weeks so I committed the tests in my name with credit
to Gemini Lasswell.

The bugs here still needs to be fixed though.

Best regards,
Stefan Kangas

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

From: Gemini Lasswell <gazally <at> runbox.com>
To: Stefan Kangas <stefan <at> marxist.se>
Cc: 28557 <at> debbugs.gnu.org, Eli Zaretskii <eliz <at> gnu.org>,
 monnier <at> iro.umontreal.ca
Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Wed, 12 Aug 2020 18:07:34 -0700

Stefan Kangas writes:
>> I don't see why not, provided that Gemini Lasswell agrees.
>
> No reply within 13 weeks so I committed the tests in my name with credit
> to Gemini Lasswell.

Sorry I missed this 13 weeks ago.  Thanks for committing the tests.

Message #28 received at 28557-done <at> debbugs.gnu.org (full text, mbox):

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Gemini Lasswell <gazally <at> runbox.com>
Cc: 28557-done <at> debbugs.gnu.org
Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
Date: Mon, 20 Dec 2021 22:05:14 -0500

> Stefan, here's a list of macros in which it appears to me that
> (:documentation FORM) is supposed to work. Is this correct?
> Am I missing any?

I don't know.  The cl-generic.el case is debatable (not sure how
important it use for it to support computed docstrings), but in any case
I think I fixed those cases now.  Thanks.

Note that I did not upgrade the Edebug specs accordingly :-(


        Stefan

Previous Next

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