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

[Stefan Monnier]

> > 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 usable.

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

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

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\\( .*\\)?)$".
> 
> 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 .elc
file, so it can't have any text-property (without significant changes).

> modifying DEFUN, adding a new 'documentation-arglist property, any other?

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