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

[Stefan Monnier]

>>> Not always, I can imagine functions defined with fset for example.

I'd consider that an error.
`defalias` on the other hand is indeed a normal and common case.

>>> What about the attached patch?  It seems to work well.
>> SGTM.  With which cases did you test this?
>> Adding Stefan, in case he has any comments.

SGTM as well.  I do have some comments, see below.

> +(defun help-function-def--find-probable-definition-place (fun)

Can we shorten the name using "guess" i.s.o "find-probable"?
Also, this should be in `find-func.el` rather than in `help-mode.el`, no?

> +  (save-excursion
> +    ;; Build a list of strings with the symbols (and strings) of FUN.
> +    (let ((names
> +           (mapcar (lambda (el)
> +                     (concat
> +                      "\\_<"
> +                      (regexp-quote (format "%s" el))

I think you want "%S" rather than "%s".

> +                      "\\_>"))
> +                   (flatten-tree (symbol-function fun))))

- We probably want to use `advice-cd*r` so as to flatten the actual
  function definition rather than the combination of its definition with
  the various pieces of advice that are currently applied.
- The above works for non-compiled functions but for byte-compiled
  functions we need an ad-hoc version of `flatten-tree` which extracts
  the constants from the constant vector of bytecode objects (also
  recursively since bytecode objects tend to contain other bytecode
  objects).
  For native-compiled functions, we may be able to get some kind of
  "constant vector" as well, but I don't think that's currently
  accessible from ELisp.  We should ask Andrea.

> +          ;; Exclude symbols that are 3 characters or less.
> +          (when (> (length el) 9)

If we filter them out when constructing `names`, we can use a comment
where the number matches the number used in the code :-)

> +                    ;; Determine the beginning position of that
> +                    ;; function.
> +                    (goto-char (point-min))
> +                    (when (catch 'found
> +                            (while (re-search-forward
> +                                    (concat "\\_<"
> +                                            (regexp-quote result)
> +                                            "\\_>"))
> +                              (when (string= (lisp-current-defun-name)
> +                                             result)
> +                                (throw 'found t)))
> +                            (throw 'found nil))
> +                      (beginning-of-defun)
> +                      (cons result (point)))))))))))))

Can't we use `find-function-noselect` here?  Or maybe just return the
function name and let the caller then use `find-function-noselect`.

> @@ -281,7 +366,31 @@ help-function-def--button-function
>              (unless (= (point) position)
>                (push-mark nil t))
>              (goto-char position))
> -        (message "Unable to find location in file")))))
> +        (let ((probable-definition-place
> +               (help-function-def--find-probable-definition-place fun)))
> +          (when probable-definition-place
> +            (goto-char (cdr probable-definition-place)))
> +          (let ((help-buffer-under-preparation t))
> +            (help-setup-xref (list #'help-function-def--button-function
> +                                   fun file)
> +                          (called-interactively-p 'interactive))
> +         (with-help-window (help-buffer)
> +           (insert (substitute-command-keys
> +                       (format "Function %s could not be found in `%s'.\n\n"
> +                              fun (file-name-nondirectory file))))
> +              (setq help-mode--current-data (list :symbol fun
> +                                                  :file file))
> +           (save-excursion
> +             (re-search-backward
> +                 (substitute-command-keys "`\\([^`']+\\)'")
> +                 nil t)
> +             (help-xref-button 1 'help-function-def fun file))
> +              (when probable-definition-place
> +                (insert (substitute-command-keys
> +                         (format "It was probably defined by `%s'.\n\n"
> +                                (car probable-definition-place)))))
> +           (insert "Function definition:\n\n")
> +           (insert (pp-to-string (symbol-function fun))))))))))

Please move this to a separate function.

Also, I'm not completely convinced what you do with the *Help* buffer
here is the UI we'll want, really.  But I don't have a good idea for
what to replace it with (yet), so we can start with that and tweak
it later.


        Stefan