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

From: Gregory Heytings <[email-masked]>
Date: Fri, 06 Jan 2023 22:52:32 +0000

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

TBH, I'm not sure this is useful anymore, if the 'definition-name' slot is 
supposed to be used for such functions (which I didn't know).  WDYT?

>> +(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?
>

Yes and yes.

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

You mean, (flatten-tree (advice--cd*r (symbol-function fun))), right?

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

Are such dynamically defined functions not always non-compiled, by 
definition?  At least with the original recipe in this feature request, 
(symbol-file 'org-babel-execute:sh) returns "lisp/org/ob-shell.elc", so it 
has been created by a byte-compiled function.

>> +          ;; 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 :-)
>

Oh yes ;-)

>> +                    ;; 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`.
>

Indeed!

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

Sure.

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

Okay.