GNU bug report logs - #55905
warn about misplaced or duplicated doc strings, `declare` or `interactive` forms

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 55905 in the body.
You can then email your comments to 55905 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: Mattias Engdegård <mattiase <at> acm.org>
To: bug-gnu-emacs <at> gnu.org
Subject: warn about misplaced or duplicated doc strings, `declare` or
 `interactive` forms
Date: Sat, 11 Jun 2022 14:07:03 +0200

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

In function definitions, doc strings, `declare` and `interactive` forms are each optional but must appear in that order and duplications are not permitted. Many violations against these rules go undetected.

The attached patch adds checks to `defun` and `defmacro`. Violations result in compilation warnings but it could be changed into hard errors if desired. It also accepts `(:documentation EXPR)` as alternative to a doc string literal, which currently doesn't work i all cases.

Applying it reveals a handful of mistakes in the Emacs source tree, and in some external packages.

[0001-function-and-macro-attribute-order-warning-patch.patch (application/octet-stream, attachment)]

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

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: 55905 <at> debbugs.gnu.org
Subject: Re: bug#55905: warn about misplaced or duplicated doc strings,
 `declare` or `interactive` forms
Date: Sat, 11 Jun 2022 14:44:59 +0200

Mattias Engdegård <mattiase <at> acm.org> writes:

> In function definitions, doc strings, `declare` and `interactive`
> forms are each optional but must appear in that order and duplications
> are not permitted. Many violations against these rules go undetected.
>
> The attached patch adds checks to `defun` and `defmacro`. Violations
> result in compilation warnings but it could be changed into hard
> errors if desired. It also accepts `(:documentation EXPR)` as
> alternative to a doc string literal, which currently doesn't work i
> all cases.

This is most welcome -- I can never remember myself what the order of
declare and interactive is.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

From: Mattias Engdegård <mattiase <at> acm.org>
To: dick <dick.r.chiang <at> gmail.com>
Cc: 55905 <at> debbugs.gnu.org
Subject: Re: bug#55905: warn about misplaced or duplicated doc strings,
 `declare` or `interactive` forms
Date: Sun, 12 Jun 2022 14:45:35 +0200

> Come offer your free labor to Commercial Emacs.  We rectified
> (and test!) the byte-compiler line annotations without vitiating the
> Lisp implementation with BASE_EQ, which I know you've wasted time on.

That's nice, but why don't you just `#define BASE_EQ EQ` and avoid gratuitous divergence from the GNU tree and save yourself some time (as well as avoiding future merge conflicts)?

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

From: dick <dick.r.chiang <at> gmail.com>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: 55905 <at> debbugs.gnu.org
Subject: Re: bug#55905: warn about misplaced or duplicated doc strings,
 `declare` or `interactive` forms
Date: Sun, 12 Jun 2022 08:14:01 -0400

Come offer your free labor to Commercial Emacs.  We rectified
(and test!) the byte-compiler line annotations without vitiating the
Lisp implementation with BASE_EQ, which I know you've wasted time on.

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

From: dick <dick.r.chiang <at> gmail.com>
To: Mattias Engdegård <mattiase <at> acm.org>
Cc: 55905 <at> debbugs.gnu.org
Subject: Re: bug#55905: warn about misplaced or duplicated doc strings,
 `declare` or `interactive` forms
Date: Sun, 12 Jun 2022 09:05:50 -0400

Ha, I considered that but the marginal cost of symbols-with-positions
conflicts wasn't sufficiently high to introduce `#define BASE_EQ EQ`.

We knew it'd be a tough sell to OG devs to turn their backs on GNU, but
we had to try.

So long as non-free software exists, we shall continue the fight (since
our operations rely on such non-free software).

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

From: Mattias Engdegård <mattiase <at> acm.org>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 55905-done <at> debbugs.gnu.org
Subject: Re: bug#55905: warn about misplaced or duplicated doc strings,
 `declare` or `interactive` forms
Date: Fri, 17 Jun 2022 17:30:17 +0200

11 juni 2022 kl. 14.44 skrev Lars Ingebrigtsen <larsi <at> gnus.org>:

> This is most welcome -- I can never remember myself what the order of
> declare and interactive is.

Same here (which prompted the patch). A slightly updated version has now been pushed to master.

There's the possibility of making the parsing more tolerant with respect to ordering, and possibly allow multiple `declare` forms. It would be easy enough.

Previous Next

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