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: Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' ) Date: Wed, 17 Jul 2002 10:33:39 -0400 Sender: emacs-devel-admin@gnu.org Message-ID: <200207171433.g6HEXe202931@rum.cs.yale.edu> References: <20020717091513.F3D1.LEKTU@terra.es> <200207171306.g6HD6uN02339@rum.cs.yale.edu> <20020717152253.4F19.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 1026916471 8386 127.0.0.1 (17 Jul 2002 14:34:31 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Wed, 17 Jul 2002 14:34:31 +0000 (UTC) Cc: "Stefan Monnier" , rms@gnu.org, 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 17Upsr-0002B9-00 for ; Wed, 17 Jul 2002 16:34:29 +0200 Original-Received: from fencepost.gnu.org ([199.232.76.164]) by quimby.gnus.org with esmtp (Exim 3.12 #1 (Debian)) id 17Uq4J-0007sK-00 for ; Wed, 17 Jul 2002 16:46:19 +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 17Upsh-0007yO-00; Wed, 17 Jul 2002 10:34: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 17Ups5-0007wz-00; Wed, 17 Jul 2002 10:33:41 -0400 Original-Received: (from monnier@localhost) by rum.cs.yale.edu (8.11.6/8.11.6) id g6HEXe202931; Wed, 17 Jul 2002 10:33:40 -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 g6HEXe202931 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:5838 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:5838 > > This is pretty easy to implement (I have the code mostly working, > Aha, I wondered about "fun" and why DEF was optional in > `help-split-fundoc' :) It's just remnants of some of my then-current code. Nothing really usabl= e. > > with the only ugliness being "where to put the functions that > > insert/extract this arglist info" since they are used by CL,=A0help-f= ns.el, > > eldoc.el, autoload.el, advice.el and maybe more. I guess the trivial > > answer is "in subr.el"). >=20 > Unless you want to add a new file to lisp/emacs-lisp/. Perhaps we shoul= d > create emacs-lisp/doc-helper.el and move some code from help-fns.el. It's at most 50 lines of code. Hardly worth a separate file. > > 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). >=20 > But I wonder if there's much code that adds to the docstring of a > function. If advice.el is the exception, we could just adapt it to "ski= p" > the arglist info. Indeed, whichever way we o, we can always get things right. But if we can reduce the amount of code necessary to get it right, I think it's a plus. > > But maybe we could put it on the > > second line such that the regexp would be something like > > "\\`.*\nUsage: (fn\\( .*\\)?)$". >=20 > Second line sounds too much special-cased to me; I'd rather have it at > the end and modify advice.el than get it from the middle of the > docstring. But seen from the point of view of the user writing the docstring for his alias, "This does foo. (blabla ARG1 &optional TOTO) When ARG1 is non-nil blabla else blibli." is IMO more readable (in the source code) than "This does foo. When ARG1 is non-nil blabla else blibli. (blabla ARG1 &optional TOTO)" In any case, I don't care much either way. > Are there other options? Puting text properties in the docstring, The docstring is often/mostly extracted from the DOC file or from the .el= c file, so it can't have any text-property (without significant changes). > modifying DEFUN, adding a new 'documentation-arglist property, any othe= r? It's good to associate it with the function rather than with the symbol to which this function is associated, so that if you do (fset 'foo (symbol-function 'bar)), the info is not lost. So using a symbol-property is a bit less attractive. In the case of autoloaded functions, putting the info in the docstring means that it quietly sits in the DOC file rather than tying up real memory. > Perhaps clearly disociating documentation from arglist would be good... Yes, of course, but it has its own shortcomings. Stefan