From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: "Stefan Monnier" Newsgroups: gmane.emacs.devel Subject: arglist in docstring (was: mentioning variable aliases in `describe-variable' ) Date: Wed, 17 Jul 2002 09:06:56 -0400 Sender: emacs-devel-admin@gnu.org Message-ID: <200207171306.g6HD6uN02339@rum.cs.yale.edu> References: <20020716131726.4190.LEKTU@terra.es> <200207170304.g6H34jg22787@aztec.santafe.edu> <20020717091513.F3D1.LEKTU@terra.es> NNTP-Posting-Host: localhost.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable X-Trace: main.gmane.org 1026911438 26061 127.0.0.1 (17 Jul 2002 13:10:38 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Wed, 17 Jul 2002 13:10:38 +0000 (UTC) Cc: rms@gnu.org, monnier+gnu/emacs@rum.cs.yale.edu, emacs-devel@gnu.org Return-path: Original-Received: from quimby.gnus.org ([80.91.224.244]) by main.gmane.org with esmtp (Exim 3.33 #1 (Debian)) id 17UoZf-0006mE-00 for ; Wed, 17 Jul 2002 15:10:35 +0200 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 17Uol5-00060C-00 for ; Wed, 17 Jul 2002 15:22:23 +0200 Original-Received: from localhost ([127.0.0.1] helo=fencepost.gnu.org) by fencepost.gnu.org with esmtp (Exim 3.35 #1 (Debian)) id 17UoXT-00047R-00; Wed, 17 Jul 2002 09:08:19 -0400 Original-Received: from rum.cs.yale.edu ([128.36.229.169]) by fencepost.gnu.org with esmtp (Exim 3.35 #1 (Debian)) id 17UoWE-0003xr-00; Wed, 17 Jul 2002 09:07:02 -0400 Original-Received: (from monnier@localhost) by rum.cs.yale.edu (8.11.6/8.11.6) id g6HD6uN02339; Wed, 17 Jul 2002 09:06:56 -0400 X-Mailer: exmh version 2.4 06/23/2000 with nmh-1.0.4 Original-To: Juanma Barranquero X-MIME-Autoconverted: from 8bit to quoted-printable by rum.cs.yale.edu id g6HD6uN02339 Errors-To: emacs-devel-admin@gnu.org X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.0.11 Precedence: bulk List-Help: List-Post: List-Subscribe: , List-Id: Emacs development discussions. List-Unsubscribe: , List-Archive: Xref: main.gmane.org gmane.emacs.devel:5828 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:5828 > On Tue, 16 Jul 2002 21:04:45 -0600 (MDT), Richard Stallman wrote: >=20 > > Perhaps the best thing is simply to tell the user how to put in the > > arglist info when making an alias for a builtin function. That is > > definitely a simple method. >=20 > I agree; it is much better than doing obscure tricks in `defalias', IMO. > But it'd be also necessary to modify `help-split-fundoc' to allow for a > different function name in the arglist info, so you can say: >=20 > (defalias 'get-item > 'aref > "Return TABLE[INDEX].\n(get-item TABLE INDEX)") >=20 > and get the arglist info (now you don't). It's definitely on my plan. This is not just for the case you mention but because I want to be able to put arglist in the docstring of autoloaded functions, as well as change defun* to put the original CL-style arglist in there, so that describe-function would say: (foobar ARG1 &key KEY1 (KEY2 default2)) instead of (foobar ARG1 &rest --CL21452--) We just have to decide on a format to use. The current format for subr's "arglist in docstring" can be described as "\n\n(\\( .*\\)?)\\'= ". Using the subroutine's name in there is annoying since it might not be the same as the symbol the subr is associated with, so the code curren= tly uses an ugly hack to find the subr's name. I'm leaning towards allowing any functions' docstring to end with "\n\n(fn\\( .*\\)?)\\'" instead. So you'd say (defalias 'get-item 'aref "Return TABLE[INDEX].\n\n(fn TABLE INDEX)") This is pretty easy to implement (I have the code mostly working, with the only ugliness being "where to put the functions that insert/extract this arglist info" since they are used by CL,=A0help-fns.e= l, eldoc.el, autoload.el, advice.el and maybe more. I guess the trivial answer is "in subr.el"). An alternative is to put this info not at the very end, but rather near the beginning of the docstring. The reason is that it works better in the case where someone appends text to the docstring (try (defadvice car (after foobar activate) 1) and then C-h f car RET to see what I'm getting at). Of course, putting it on the first line is probably out because the first line is handled specially in a few places and it'd be better not to have to change those. But maybe we could put it on the second line such that the regexp would be something like "\\`.*\nUsage: (fn\\( .*\\)?)$". Stefan