From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Lars Ingebrigtsen Newsgroups: gmane.emacs.bugs Subject: bug#19371: 25.0.50; doc of functions and macros defined in macroexp.el Date: Fri, 02 Aug 2019 23:10:43 +0200 Message-ID: <87v9vfl1d8.fsf@mouse.gnus.org> References: <1b8c129f-19cb-4088-ad8a-4eb0f9df6a54@default> Mime-Version: 1.0 Content-Type: text/plain Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="70129"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: 19371@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Aug 02 23:11:14 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1htepV-000Hx5-OQ for geb-bug-gnu-emacs@m.gmane.org; Fri, 02 Aug 2019 23:11:13 +0200 Original-Received: from localhost ([::1]:37572 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1htepU-00006q-Q6 for geb-bug-gnu-emacs@m.gmane.org; Fri, 02 Aug 2019 17:11:12 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:42991) by lists.gnu.org with esmtp (Exim 4.86_2) (envelope-from ) id 1htepO-0008VY-2m for bug-gnu-emacs@gnu.org; Fri, 02 Aug 2019 17:11:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1htepN-0001IZ-0z for bug-gnu-emacs@gnu.org; Fri, 02 Aug 2019 17:11:06 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:49099) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1htepK-0001Ey-L4 for bug-gnu-emacs@gnu.org; Fri, 02 Aug 2019 17:11:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1htepK-0004HD-Ex for bug-gnu-emacs@gnu.org; Fri, 02 Aug 2019 17:11:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Lars Ingebrigtsen Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 02 Aug 2019 21:11:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 19371 X-GNU-PR-Package: emacs Original-Received: via spool by 19371-submit@debbugs.gnu.org id=B19371.156478025016420 (code B ref 19371); Fri, 02 Aug 2019 21:11:02 +0000 Original-Received: (at 19371) by debbugs.gnu.org; 2 Aug 2019 21:10:50 +0000 Original-Received: from localhost ([127.0.0.1]:57920 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1htep8-0004Gm-IQ for submit@debbugs.gnu.org; Fri, 02 Aug 2019 17:10:50 -0400 Original-Received: from quimby.gnus.org ([80.91.231.51]:36182) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1htep6-0004Gc-Mn for 19371@debbugs.gnu.org; Fri, 02 Aug 2019 17:10:49 -0400 Original-Received: from 77.18.62.220.tmi.telenormobil.no ([77.18.62.220] helo=sandy) by quimby.gnus.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1htep2-00067v-8M; Fri, 02 Aug 2019 23:10:46 +0200 In-Reply-To: <1b8c129f-19cb-4088-ad8a-4eb0f9df6a54@default> (Drew Adams's message of "Sat, 13 Dec 2014 11:04:24 -0800 (PST)") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:164400 Archived-At: Drew Adams writes: > 1. `macroexp-let2' is used plenty in the Lisp sources now. And its > documentation is in complete/rudimentary. Please fix this. Looks like Paul added extensive documentation to this macro i 2015. > 2. And then there is `macroexp-let2*', whose doc string says only to > bind each binding (bind a binding?!) "as `macrolet2' does". That > means nothing. Presumably, based on the `*' in the name, the behavior > is similar to that of `let*'. If so, you can use the doc of `let* > as inspiration. Uhm... I have no idea what it does: (defmacro macroexp-let2* (test bindings &rest body) "Bind each binding in BINDINGS as `macroexp-let2' does." (declare (indent 2) (debug (sexp (&rest (sexp form)) body))) (pcase-exhaustive bindings ('nil (macroexp-progn body)) (`((,var ,exp) . ,tl) `(macroexp-let2 ,test ,var ,exp (macroexp-let2* ,test ,tl ,@body))))) Perhaps somebody could use their decoder ring. > 3. The doc strings of `macroexp-let*', `macroexp-progn', and others > say that the function returns "an expression equivalent to" some > expression. They should say what they mean by equivalence, here. > If you mean that they use `macroexp-quote' to create the > "equivalent" expression then say so. No, the meaning here seems to be that they are semantically equivalent. I changed the doc string of macroexp-progn to "Return EXPS with `progn' prepended. If EXPS is a single expression, `progn' is not prepended." but I think the rest are OK. > The doc string of `macroexp-let*' needs to use BINDINGS and EXP, not > the same in lowercase, in the equivalent expression. I've now fixed this. > Similarly, the doc string of `macroexp-if' needs to use uppercase > TEST, THEN, and ELSE. Somebody else has fixed that in the intervening years. > 4. The doc string of `macroexp--accumulate' refers to parameters > that do not exist: VAR and LIST. It should say explicitly (and > not just via `(fn ...)') that the first parameter is a list of > the form `(VAR LIST)'. (And no, it does not matter that this > macro is internal.) This has been fixed, too. > 5. The doc string of `macroexp--cons' is incomprehensible. I've now fixed it. -- (domestic pets only, the antidote for overdose, milk.) bloggy blog: http://lars.ingebrigtsen.no