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

[Juanma Barranquero <lektu@terra.es>]

On Wed, 17 Jul 2002 09:06:56 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> 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

Very nice.

> 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' :)

> 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").

Unless you want to add a new file to lisp/emacs-lisp/. Perhaps we should
create emacs-lisp/doc-helper.el and move some code from help-fns.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).

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 "skip"
the arglist info.

> But maybe we could put it on the
> second line such that the regexp would be something like
> "\\`.*\nUsage: (fn\\( .*\\)?)$".

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.

Are there other options? Puting text properties in the docstring,
modifying DEFUN, adding a new 'documentation-arglist property, any other?
Perhaps clearly disociating documentation from arglist would be good...


                                                           /L/e/k/t/u