Subject: bug#28557: closed (Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures)

From: [email-masked] (GNU bug Tracking System)
Date: Tue, 21 Dec 2021 03:06:02 +0000

Your bug report

#28557: 26.0.60; Bugs using (:documentation FORM) in closures

which was filed against the emacs package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
28557: http://debbugs.gnu.org/cgi/bugreport.cgi?bug=28557
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#28557: 26.0.60; Bugs using (:documentation FORM) in closures
From: Stefan Monnier <[email-masked]>
To: Gemini Lasswell <[email-masked]>
Cc: [email-masked]
Date: Mon, 20 Dec 2021 22:05:14 -0500
List-Id: <debbugs-submit.debbugs.gnu.org>

> 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

Subject: 26.0.60; Bugs using (:documentation FORM) in closures
From: Gemini Lasswell <[email-masked]>
To: [email-masked]
Date: Fri, 22 Sep 2017 10:30:11 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

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:

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