bug#60568: [FR] 30.0.50; Help buffers and function bodies for generated functions

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Date: Thu, 05 Jan 2023 07:56:11 +0000
> 
> There have been a discussion [1] about including some of the helpful
> package [2] features into built-in *Help* buffers.
> 
> One of the discussed features was displaying function source code right
> in *Help* buffers. This feature usefulness have been objected at that
> time, on the grounds that showing function code may be too long and
> cause large *Help* buffers.
> 
> Recently, we have stumbled upon a situation when showing function code
> is not only useful, but one of the few sane ways to examine it [3].
> Functions that are not directly written in the source but rather
> generated programmatically cannot currently be easily examined using
> built-in help functionality (using describe-function or other means).
> The help buffer only links to the (point-min) in the library defining
> the generated function - not very helpful. In contrast, helpful extracts
> function body from symbol function slot.
> 
> To illustrate, one can try the following:
> 
> 1. emacs -Q
> 2. M-: (require 'ob-shell)
> 3. <F1> f org-babel-execute:sh <RET>
> 4. Click on the source code link in *Help* buffer
> 5. Observe point jumping to (point-min) with no obvious way to find the
>    function definition.
> 
> Would it be possible to provide function body info via *Help* system in
> Emacs?

Provide how?

You basically ignore the valid objections voiced against such a
feature, and present a specific case where (a) the source code is
extremely short, and (b) the existing Help facilities are less than
helpful because they have a deficiency.  How does it follow from the
specific use case you present that we must show the source code in
Help buffers?  An alternative solution would be to teach Help
functions to find the place where the source code is generated and let
users examine that if they want.  I could even argue that this
alternative is better, because with your proposal we will show a
source code that doesn't actually exist anywhere in the form we show
it.

If we do decide to show the source code in some circumstances, we need
to do that selectively and in a way that doesn't display unnecessarily
large Help buffers that would then run the risk of "drowning" useful
information, making it easy to miss.  So any such proposal should
suggest how to avoid the downsides, at least.