From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#19371: 25.0.50; doc of functions and macros defined in macroexp.el Date: Sat, 13 Dec 2014 11:04:24 -0800 (PST) Message-ID: <1b8c129f-19cb-4088-ad8a-4eb0f9df6a54@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1418497597 32349 80.91.229.3 (13 Dec 2014 19:06:37 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 13 Dec 2014 19:06:37 +0000 (UTC) To: 19371@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Dec 13 20:06:30 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Xzs1M-0002eP-Jt for geb-bug-gnu-emacs@m.gmane.org; Sat, 13 Dec 2014 20:06:28 +0100 Original-Received: from localhost ([::1]:34042 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xzs1L-0004Nx-RG for geb-bug-gnu-emacs@m.gmane.org; Sat, 13 Dec 2014 14:06:27 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55705) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xzs17-0004NZ-Dm for bug-gnu-emacs@gnu.org; Sat, 13 Dec 2014 14:06:23 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xzs0x-0004zB-1j for bug-gnu-emacs@gnu.org; Sat, 13 Dec 2014 14:06:13 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:35650) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xzs0w-0004z6-Ud for bug-gnu-emacs@gnu.org; Sat, 13 Dec 2014 14:06:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1Xzs0w-00023D-HN for bug-gnu-emacs@gnu.org; Sat, 13 Dec 2014 14:06:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 13 Dec 2014 19:06:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 19371 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.14184975077812 (code B ref -1); Sat, 13 Dec 2014 19:06:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 13 Dec 2014 19:05:07 +0000 Original-Received: from localhost ([127.0.0.1]:45016 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Xzs02-00021v-Ou for submit@debbugs.gnu.org; Sat, 13 Dec 2014 14:05:07 -0500 Original-Received: from eggs.gnu.org ([208.118.235.92]:53843) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Xzs00-00021N-9D for submit@debbugs.gnu.org; Sat, 13 Dec 2014 14:05:05 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xzrzk-0004Jl-LH for submit@debbugs.gnu.org; Sat, 13 Dec 2014 14:04:58 -0500 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:50219) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xzrzk-0004JV-I6 for submit@debbugs.gnu.org; Sat, 13 Dec 2014 14:04:48 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55475) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xzrzb-0004Gj-PG for bug-gnu-emacs@gnu.org; Sat, 13 Dec 2014 14:04:48 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XzrzT-0004EV-10 for bug-gnu-emacs@gnu.org; Sat, 13 Dec 2014 14:04:39 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:24056) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XzrzS-0004EQ-QJ for bug-gnu-emacs@gnu.org; Sat, 13 Dec 2014 14:04:30 -0500 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id sBDJ4QJG027730 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sat, 13 Dec 2014 19:04:27 GMT Original-Received: from userz7022.oracle.com (userz7022.oracle.com [156.151.31.86]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id sBDJ4PVF006249 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 13 Dec 2014 19:04:26 GMT Original-Received: from abhmp0019.oracle.com (abhmp0019.oracle.com [141.146.116.25]) by userz7022.oracle.com (8.14.5+Sun/8.14.4) with ESMTP id sBDJ4O0C006222 for ; Sat, 13 Dec 2014 19:04:24 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8.2 (807160) [OL 12.0.6691.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:97296 Archived-At: 1. `macroexp-let2' is used plenty in the Lisp sources now. And its documentation is in complete/rudimentary. Please fix this. 1a. It is not even mentioned in the Elisp manual. Please document it=20 properly there. 1b. The doc string says: "Bind VAR to a copyable expression that returns the value of EXP. This is like `(let ((v ,EXP)) ,EXPS) except that `v' is a new generated symbol which EXPS can find in VAR." What on Earth does it mean for EXPS to find the symbol `v' in VAR? VAR is a symbol. What does it mean for a list of expressions to find another symbol "in" symbol VAR? Just what does it mean for the expression to which VAR is bound to be "copyable" or not "copyable"? If you mean `macroexp-copyable-p' then say so. I'm only presuming that EXPS is a list of Lisp sexps. It is not even described, but it needs to be. Nor is EXP described, for that matter. I'm guessing that it is a Lisp sexp, but it too needs to be specified properly. What does it mean for "the `let'" to be skipped"? How is TEST really used - what is it for? So far, this macro description is gobbledygook. Please document the macro properly. 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. 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. The doc string of `macroexp-let*' needs to use BINDINGS and EXP, not the same in lowercase, in the equivalent expression. Similarly, the doc string of `macroexp-if' needs to use uppercase TEST, THEN, and ELSE. 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.) 5. The doc string of `macroexp--cons' is incomprehensible. In GNU Emacs 25.0.50.1 (i686-pc-mingw32) of 2014-11-30 on LEG570 Bzr revision: 3517da701ea5d16c296745d6678988b06bee615d Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --without-dbus --enable-checking=3Dyes,glyphs CPPFLAGS=3D-DGLYPH_DEBUG=3D1'