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#14278: 24.3.50; doc of `defstruct' Date: Fri, 26 Apr 2013 13:29:31 -0700 Message-ID: <66929FFAEED944A9872AEF400BED6815@us.oracle.com> References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1367008206 32611 80.91.229.3 (26 Apr 2013 20:30:06 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 26 Apr 2013 20:30:06 +0000 (UTC) To: <14278@debbugs.gnu.org> Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Apr 26 22:30:08 2013 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 1UVpHT-00050u-Bk for geb-bug-gnu-emacs@m.gmane.org; Fri, 26 Apr 2013 22:30:07 +0200 Original-Received: from localhost ([::1]:52184 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UVpHS-00034B-Vd for geb-bug-gnu-emacs@m.gmane.org; Fri, 26 Apr 2013 16:30:06 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:58953) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UVpHP-00033a-QN for bug-gnu-emacs@gnu.org; Fri, 26 Apr 2013 16:30:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1UVpHN-0005C9-5l for bug-gnu-emacs@gnu.org; Fri, 26 Apr 2013 16:30:03 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:41316) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1UVpHM-0005Bl-Qe for bug-gnu-emacs@gnu.org; Fri, 26 Apr 2013 16:30:00 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72) (envelope-from ) id 1UVpHO-0008UN-K0 for bug-gnu-emacs@gnu.org; Fri, 26 Apr 2013 16:30:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 26 Apr 2013 20:30:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 14278 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 14278-submit@debbugs.gnu.org id=B14278.136700818432561 (code B ref 14278); Fri, 26 Apr 2013 20:30:02 +0000 Original-Received: (at 14278) by debbugs.gnu.org; 26 Apr 2013 20:29:44 +0000 Original-Received: from localhost ([127.0.0.1]:45424 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UVpH6-0008T8-3V for submit@debbugs.gnu.org; Fri, 26 Apr 2013 16:29:44 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:34515) by debbugs.gnu.org with esmtp (Exim 4.72) (envelope-from ) id 1UVpH3-0008Sx-Ex for 14278@debbugs.gnu.org; Fri, 26 Apr 2013 16:29:42 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r3QKTb9v024988 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL) for <14278@debbugs.gnu.org>; Fri, 26 Apr 2013 20:29:38 GMT Original-Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3QKTat5009939 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL) for <14278@debbugs.gnu.org>; Fri, 26 Apr 2013 20:29:37 GMT Original-Received: from abhmt111.oracle.com (abhmt111.oracle.com [141.146.116.63]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r3QKTaFn009930 for <14278@debbugs.gnu.org>; Fri, 26 Apr 2013 20:29:36 GMT Original-Received: from dradamslap1 (/10.159.138.219) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Fri, 26 Apr 2013 13:29:36 -0700 X-Mailer: Microsoft Office Outlook 11 In-reply-to: Thread-Index: Ac5CuMCF06UyZET0Sw6siS1npR1odQAAWzGA X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.13 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.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:73748 Archived-At: > Both the doc string and (cl) `Structures' are a bit sloppy in their > descriptions. SLOTS is the name of one parameter. It is incorrect to > speak of SLOT unless that has been defined as one of the elements of > list SLOTS. And it needs in fact to be said that SLOTS is a list. > > The doc string says "Each SLOT may instead..." - instead of what? It > forgets to say that a slot can be a symbol. Things are worse than that, in fact. 1. The manual says that each element of SLOT, if not a symbol, is a list (SLOT-NAME DEFAULT-VALUE SLOT-OPTIONS...). But the doc string says it is (SLOT SLOT-OPTS...), forgetting DEFAULT-VALUE altogether. 2. The manual does not say what each element of SLOT-OPTIONS is. The doc string at least says that SLOT-OPTS is a list of key value pairs. Both manual and doc string would be better off saying that SLOT-OPT[ION]S is a plist, and describe what the keys and values of the plist can be. 3. The same problems reported originally for SLOTS exist also for NAME. It speaks of OPTION without giving that term any relation to OPTIONS. 4. The doc string does not say that NAME can be a symbol. The manual says that NAME can be a list of a symbol followed by "struct options" (it should presumably say "structure options", since that is the term used elsewhere in the node). But the manual does not say that a structure option here is either a KEYWORD or a pair (KEYWORD VALUE). In this case the doc string is more complete (assuming it is correct here) - the manual provides no help with this. 5. It is misleading and confusing to write "NAME may instead take the form (NAME OPTIONS...)". That sounds like a recursive definition, allowing for, say, NAME to be (foo (foo (foo ...) bar))). Use two different names: NAME and NAME1 or something, else it is impossible to know when you are referring to the parameter and when you are referring to one of its parts.