RE: (fn ...) - please fill it at the point of generation

[Drew Adams]

> >> It's really not part of the doc string as such, it's an interface
> >> description.
> >
> > That's a good feint. This part of the doc string isn't right, so to fix
> > things we'll just say it's not part of the doc string.
>
> No, it was always intended as a function signature, not a text string
> for display.  It's put into the _raw_ docstring because that's a
> convenient place to put it, but it is intended that this be filtered
> appropriately for display.

If the signature text is not intended as part of the doc string, then it and
the doc string should each be available separately, not joined at the hip
from birth. Function `documentation' (or some other function) should return
only the doc string per se, and some other function (e.g. `signature')
should return the signature (interface spec).

In my use of it, I display a buffer which includes function names and doc
strings of functions that match an input regexp. It can thus include all
defined functions. That's between 8000 and 9000 doc strings at the start of
an Emacs session, in my environment at least. I fit the buffer's frame
automatically, which takes into account the longest line (250 chars - from a
signature).

You can change your input regexp on the fly, and the matching function names
and doc strings are updated (and the frame is refit). It would be
unreasonable to examine each matching doc string, try to determine whether
it in fact contained a (fn...) signature, and, if so, fill that signature.
Unreasonable in terms of performance and, I maintain, unreasonable in terms
of Emacs design.

Currently, AFAIK, the only function I have available to retrieve the doc
string is `documentation', and that currently includes the problematic line
that you are saying should not be considered to be part of the doc string.
Practically speaking, it *is* part of the doc string (it is included by
`documentation'), but OK, it shouldn't be.

If you want to maintain the independence of the signature from the doc
string, fine. But in that case, please do it right - provide a separate
function that will retrieve only the doc string.