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#15031: 24.3.50; doc for `(cl-)defstruct' and its generated functions Date: Mon, 5 Aug 2013 17:06:54 -0700 (PDT) Message-ID: 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 1375747712 12768 80.91.229.3 (6 Aug 2013 00:08:32 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 6 Aug 2013 00:08:32 +0000 (UTC) To: 15031@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Aug 06 02:08:33 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 1V6UpE-0001Ci-KW for geb-bug-gnu-emacs@m.gmane.org; Tue, 06 Aug 2013 02:08:32 +0200 Original-Received: from localhost ([::1]:53188 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6UpD-00030v-Jj for geb-bug-gnu-emacs@m.gmane.org; Mon, 05 Aug 2013 20:08:31 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36623) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Up1-0002xg-Eu for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:08:29 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V6Uol-000163-Sm for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:08:19 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:47764) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Uol-00015s-N5 for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:08:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1V6Uol-0000Aq-1K for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:08:03 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 06 Aug 2013 00:08:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 15031 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.1375747658630 (code B ref -1); Tue, 06 Aug 2013 00:08:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 6 Aug 2013 00:07:38 +0000 Original-Received: from localhost ([127.0.0.1]:42079 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V6UoL-0000A5-N7 for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:38 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:34810) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1V6UoI-00009r-Jo for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:35 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V6Uo3-0000k9-7f for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:29 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:52360) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Uo3-0000k5-4J for submit@debbugs.gnu.org; Mon, 05 Aug 2013 20:07:19 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:36512) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Unu-0002kC-FI for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:18 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1V6Unl-0000gv-SN for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:10 -0400 Original-Received: from aserp1040.oracle.com ([141.146.126.69]:31564) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1V6Unl-0000gk-Dq for bug-gnu-emacs@gnu.org; Mon, 05 Aug 2013 20:07:01 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r7606xgC022941 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Tue, 6 Aug 2013 00:07:00 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 r7606wms028131 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Tue, 6 Aug 2013 00:06:58 GMT Original-Received: from abhmt108.oracle.com (abhmt108.oracle.com [141.146.116.60]) by userz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7606vZW029784 for ; Tue, 6 Aug 2013 00:06:57 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6668.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:76987 Archived-At: 1. You can add a doc string to a defstruct structure. But this is very poorly documented. For one thing, it is excluded from the doc string. For another thing what is said about it in (cl) `Structures' is buried so as to be almost imperceptible, and is anyway not clear: -- Macro: cl-defstruct name slots... The `cl-defstruct' form defines a new structure type called NAME, with the specified SLOTS. (The SLOTS may begin with a string ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ which documents the structure type.) In the simplest case... ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Please help users more than this. 2. The doc string is anyway not used/usable by users! It is the value of property `structure-documentation', but there is no Emacs command that offers it up in *Help*. Please provide this help in some form for users. 3. There is a real problem for each of the functions defined by `(cl-)defstruct': None of them have a doc string. Defstruct itself provides no way to provide a doc string for them. Please provide some simple way to do this, even at the possible cost of deviating from the Common Lisp defstruct definition. We already deviate from it in important ways (it does not define a real type etc.). The least we can do is provide standard Emacs features such as doc strings for the generated functions. Among other things, this will help discoverability. And it will help you understand why, if you do use `C-h f' on such a function name and you click its source link, that takes you to a `defstruct' in the source file. This is not obvious. When you get to the source file you find no defun for the function. In fact, you cannot find the function at all - its name is nowhere to be seen. All of that is "normal", except the fact that Emacs `(cl-)defstruct' does not provide for attaching doc strings to such functions. Yes, a programmer could attach doc in a roundabout way, but they do not seem to be doing so. ;-). In GNU Emacs 24.3.50.1 (i686-pc-mingw32) of 2013-08-02 on ODIEONE Bzr revision: 113660 lekktu@gmail.com-20130802160313-rbi3o6322mz0m3ye Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/Devel/emacs/binary --enable-checking=3Dyes,glyphs CFLAGS=3D-O0 -g3 LDFLAGS=3D-Lc:/Devel/emacs/lib CPPFLAGS=3D-Ic:/Devel/emacs/include'