bug#66750: help-split-fundoc (was: bug#66750: Unhelpful text in C-h v for variables with a lambda form as value)

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

>> The way we do it for the arglist is hideous and a pain in the rear (I
>> blame the maintainers who accepted my patch back then), so it would be
>> an opportunity to "do it right" this time.
> What is bad about it, and how do you propose it could be improved?

It shouldn't be hidden under a `help-` prefix.
`help-split-fundoc` should not return "either a cons or nil".
Things like that.
It's clunky.

Part of the problem is that arglists often need to be
manipulated/provided by macros whose output is a language that only
knows about docstrings and not arglists, so it necessarily exposes
this hack of storing the arglist inside the docstring.
It's somewhat difficult to make it much better without significant
changes elsewhere (like an extension to the syntax of `lambda` where we
can provide side info like arglists).

Maybe it would help to rename `function-documentation` to `function-info`
whose output is type shouldn't matter because we only access it via
other functions like `function-info-documentation`,
`function-info-arglist`, ...
And then provide a (function-info-join INFO TYPE VALUE) where type can
be `documentation` or `arglist` or ...

The function arglist thingy was originally designed so that function
arglists could be easily provided from the DEFUNs in the C code, so it
was important to use a syntax that was somewhat human-readable, but it's
not indispensable to use the same format in the DEFUNs as elsewhere, so
we could choose a less human-friendly encoding that's more robust and
easier to extend.


        Stefan