arglist in docstring (was: mentioning variable aliases in `describe-variable' )

["Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>]

> On Tue, 16 Jul 2002 21:04:45 -0600 (MDT), Richard Stallman <rms@gnu.org> wrote:
> 
> > 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.
> 
> 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:
> 
> (defalias 'get-item
>           'aref
>           "Return TABLE[INDEX].\n(get-item TABLE INDEX)")
> 
> 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(<subrname>\\( .*\\)?)\\'".
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 currently
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, help-fns.el,
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