Path & Demo: Source View in Help Buffers

Path & Demo: Source View in Help Buffers

[Arthur Miller]

[-- Attachment #1: Type: text/plain, Size: 772 bytes --]


I had some fun and implemented somewhat different version of how code is
fetched, and buttonized toggle function.

Since I really didn't got much more input than what Martin gave me yesterday, I
have had some fun and recorded a small demo of how it looks like:

https://youtu.be/yiS1eXdgcYI

Sorry, but I don't have better place to put it on, use yt-download if you prefer
not to open it in a web browser. It is just a two minute of me showing how it
looks when used in practice. I reason that looking at the code is one thing,
seeing it is the other.

I have also changed it a bit, and pasting the source after the navigation
buttons. so they don't jump out of the screen when a function is very big. Don't
know if it is better strategy, it is just a prototype anyway.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Display-source-code-in-help-mode-buffers.patch --]
[-- Type: text/x-patch, Size: 8814 bytes --]

From cd49759ff81466e31e4c96276dcdb2ff6d378d0f Mon Sep 17 00:00:00 2001
From: Arthur Miller <arthur.miller@live.com>
Date: Wed, 22 Sep 2021 01:47:41 +0200
Subject: [PATCH] Display source code in 'help-mode' buffers

* lisp/help-mode.el (help-mode-inline-source): New option.
(help--fetch-c-src): New function.
(help--fetch-lisp-src): New function.
(help--insert-source): New function.
(help--remove-source): New function.
(help--toggle-source-view): New function.
(help-source-view): New button.
(help-make-xrefs): Check for 'help-mode-inline-source' and
call 'help--insert-source' to perform insertion when possible.
---
 lisp/help-mode.el | 165 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 160 insertions(+), 5 deletions(-)

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 551cf7e1a3..bec7d25270 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -149,6 +149,16 @@ help-mode-hook
   "Hook run by `help-mode'."
   :type 'hook
   :group 'help)
+
+(defcustom help-mode-inline-source nil
+  "Display inlined source code in `help-mode' buffers.
+
+When enabled the source code of a symbol currently shown in the
+help-buffer will be displayed inlined in the help buffer, if the
+source code for the symbol is available."
+  :type 'boolean
+  :group 'help
+  :version "28.1")
 \f
 ;; Button types used by help
 
@@ -367,6 +377,11 @@ 'help-news
     (view-buffer-other-window (find-file-noselect file))
     (goto-char pos))
   'help-echo (purecopy "mouse-2, RET: show corresponding NEWS announcement"))
+
+(define-button-type 'help-source-view
+  :supertype 'help-xref
+  'help-function #'help-toggle-source-view
+  'help-echo (purecopy "mouse-2, RET: toggle source view in help-buffer"))
 \f
 (defvar bookmark-make-record-function)
 (defvar help-mode--current-data nil)
@@ -503,6 +518,115 @@ describe-symbol-backends
     and a frame), inserts the description of that symbol in the current buffer
     and returns that text as well.")
 
+(defun help--fetch-c-src (symbol type file)
+  "Find C source code for a Lisp SYMBOL in a FILE.
+
+symbol - the symbol to find.
+type - the type as obtained by 'describe-*' functions.
+file - the source file to search in."
+  (let (src beg)
+    (setq file (expand-file-name file source-directory))
+    (when (file-readable-p file)
+      (with-temp-buffer
+        (insert-file-contents-literally file)
+        (delay-mode-hooks (funcall 'c-mode))
+        (goto-char (point-min))
+        (unless type
+          (require 'find-func)
+          ;; Either or both an alias and its target might be advised.
+          (setq symbol (find-function-advised-original
+		            (indirect-function
+		             (find-function-advised-original symbol)))))
+        (when (re-search-forward
+	       (if type
+		   (concat "DEFVAR[A-Z_]*[ \t\n]*([ \t\n]*\""
+			   (regexp-quote (symbol-name symbol))
+			   "\"")
+	         (concat "DEFUN[ \t\n]*([ \t\n]*\""
+		         (regexp-quote (subr-name (advice--cd*r symbol)))
+		         "\""))
+	       nil t)
+          (if type ;; defvar here
+              (progn
+                (goto-char (line-beginning-position))
+                (skip-chars-forward "[\s\t\n\r]")
+                (setq beg (point))
+                (re-search-forward ");$" nil t)
+                (narrow-to-region beg (point)))
+            ;;(narrow-to-defun)
+            (and (re-search-backward "DEFUN" nil t)
+                 (setq beg (point))
+                 (re-search-forward ")[\n\s\t\r]*{")
+                 (re-search-forward "^}[\n\s\t\r]+")
+                 (narrow-to-region beg (point))))
+          (if (fboundp 'font-lock-ensure)
+               (font-lock-ensure)
+             (with-no-warnings (font-lock-fontify-buffer)))
+          (setq src (buffer-string)))))
+    src))
+
+(defun help--fetch-lisp-src (symbol type file)
+  "Find emacs-lisp source code for a Lisp SYMBOL in a FILE.
+
+symbol - the symbol to find.
+type - the type as obtained by 'describe-*' functions.
+file - the source file to search in."
+  (let (src pos)
+    (when file
+      (setq file (or file (find-lisp-object-file-name symbol type))))
+    (with-temp-buffer
+      (insert-file-contents file)
+      (delay-mode-hooks (funcall 'emacs-lisp-mode))
+      (require 'find-func)
+      ;; Either or both an alias and its target might be advised.
+      ;; (setq symbol (find-function-advised-original
+      ;;   	    (indirect-function
+      ;;   	     (find-function-advised-original symbol)))))
+      (setq pos (cdr (find-function-search-for-symbol symbol type file)))
+      (when pos
+        (goto-char pos)
+        (forward-sexp)
+        (narrow-to-region pos (point))
+        (if (fboundp 'font-lock-ensure)
+            (font-lock-ensure)
+          (with-no-warnings (font-lock-fontify-buffer)))
+        (setq src (buffer-string))))
+    src))
+
+(defun help--insert-source ()
+  "Fnd and insert source for the current symbol into the help-mode
+buffer."
+  (with-silent-modifications
+    (with-current-buffer (help-buffer)
+      (save-excursion
+        (let* ((file (plist-get help-mode--current-data :file))
+               (type (plist-get help-mode--current-data :type))
+               (sym (plist-get help-mode--current-data :symbol))
+               (src "Source code not available."))
+          (when (eq file 'C-source)
+            (setq file (help-C-file-name (indirect-function sym) 'fun)))
+          (setq src (if (string-suffix-p ".c" file)
+                        (help--fetch-c-src sym type file)
+                      (help--fetch-lisp-src sym type file)))
+          (goto-char (point-max))
+          (let ((end (point)))
+            (when (search-backward "View Source Code:" nil t)
+              (delete-region (point) end)
+              (help-insert-xref-button "Hide Source Code:" 'help-source-view)
+              (insert (concat "\n" src "\n")))))))))
+
+(defun help--remove-source ()
+  "Remove source code from the help buffer when present."
+  (with-current-buffer (help-buffer)
+    (with-silent-modifications
+      (save-excursion
+        (goto-char (point-max))
+        (let ((end (point)))
+          (when (search-backward "Hide Source Code:" nil t)
+            (delete-region (point) end)
+            (help-insert-xref-button
+             "View Source Code:" 'help-source-view)))))))
+
 ;;;###autoload
 (defun help-make-xrefs (&optional buffer)
   "Parse and hyperlink documentation cross-references in the given BUFFER.
@@ -664,7 +788,25 @@ help-make-xrefs
             (help-insert-xref-button help-forward-label 'help-forward
                                      (current-buffer)))
           (when (or help-xref-stack help-xref-forward-stack)
-            (insert "\n")))
+            (insert "\n"))
+          (insert "\n")
+          ;; get source string if needed and available
+          ;; describe-symbol does not produce 'current-data' plist
+          (unless help-mode--current-data
+            (save-excursion
+              (goto-char (point-min))
+              (when (re-search-forward "\\.\\(el\\|c\\)" nil t)
+                (goto-char (- (point) 2))
+                (let ((props (get-text-property (point) 'help-args)))
+                  (when props
+                    (setq help-mode--current-data
+                          (list :symbol (nth 0 props)
+                                :file (nth 1 props))))))))
+          (if help-mode-inline-source
+              (progn
+                (insert "View Source Code:") ;; just a little hack
+                (help--insert-source))
+            (help-insert-xref-button "View Source Code:" 'help-source-view)))
         (set-buffer-modified-p old-modified)))))
 
 ;;;###autoload
@@ -819,10 +961,23 @@ help-do-xref
                         (append args (list (generate-new-buffer-name "*info*")))
                       args))))
 
-;; The doc string is meant to explain what buttons do.
-(defun help-follow-mouse ()
-  "Follow the cross-reference that you click on."
-  (declare (obsolete nil "28.1"))
+(defun help-toggle-source-view ()
+  "Toggle source code display in help buffer for the current symbol."
+  (interactive)
+  (when (get-buffer-window (help-buffer))
+    (with-current-buffer (help-buffer)
+      (unless (plist-get help-mode--current-data :file)
+        (error "Source file for the current help item is not defined"))
+      (save-excursion
+        (goto-char (point-min))
+        (if (search-forward "Hide Source Code:" nil t)
+            (help--remove-source)
+          (help--insert-source))))))
+
+  ;; The doc string is meant to explain what buttons do.
+  (defun help-follow-mouse ()
+    "Follow the cross-reference that you click on."
+    (declare (obsolete nil "28.1"))
   (interactive)
   (error "No cross-reference here"))
 
-- 
2.33.0

Re: Path & Demo: Source View in Help Buffers

[Tassilo Horn]

Arthur Miller <arthur.miller@live.com> writes:

Hi Arthur,

> I had some fun and implemented somewhat different version of how code
> is fetched, and buttonized toggle function.
>
> Since I really didn't got much more input than what Martin gave me
> yesterday, I have had some fun and recorded a small demo of how it
> looks like:
>
> https://youtu.be/yiS1eXdgcYI

Really cool.  I like it. :-)

Out of curiosity, why do you have fboundp-checks for font-lock-ensure in
the code?  That's always true, isn't it?

Bye,
Tassilo

Re: Path & Demo: Source View in Help Buffers

[Arthur Miller]

Tassilo Horn <tsdh@gnu.org> writes:

> Arthur Miller <arthur.miller@live.com> writes:
>
> Hi Arthur,
>
>> I had some fun and implemented somewhat different version of how code
>> is fetched, and buttonized toggle function.
>>
>> Since I really didn't got much more input than what Martin gave me
>> yesterday, I have had some fun and recorded a small demo of how it
>> looks like:
>>
>> https://youtu.be/yiS1eXdgcYI
>
> Really cool.  I like it. :-)
Thanks!

> Out of curiosity, why do you have fboundp-checks for font-lock-ensure in
> the code?  That's always true, isn't it?

I don't know. Since font-lock has all its stuff abstracted into buffer local
function variables, I am not sure if I can count it is not nil?

If I can I would gladly remove the check. I appreciate advice, I am not so
familiar with all the details of everything.

Re: Path & Demo: Source View in Help Buffers

[Tassilo Horn]

Arthur Miller <arthur.miller@live.com> writes:

>> Out of curiosity, why do you have fboundp-checks for font-lock-ensure
>> in the code?  That's always true, isn't it?
>
> I don't know. Since font-lock has all its stuff abstracted into buffer
> local function variables, I am not sure if I can count it is not nil?

But it's no buffer-local variable, it's a function.  If you have emacs
25.1 upwards, you have `font-lock-ensure'.

> If I can I would gladly remove the check. I appreciate advice, I am
> not so familiar with all the details of everything.

I think that's a common check for 3rd-party packages which want to keep
supporting emacs 24.  But since you are hacking emacs core, there's no
need for that unless the function/variable is only defined if some
configure option is given or some lib is available.  But none of the
latter applies to font-lock.el.

Bye,
Tassilo

Re: Path & Demo: Source View in Help Buffers

[Arthur Miller]

Tassilo Horn <tsdh@gnu.org> writes:

> Arthur Miller <arthur.miller@live.com> writes:
>
>>> Out of curiosity, why do you have fboundp-checks for font-lock-ensure
>>> in the code?  That's always true, isn't it?
>>
>> I don't know. Since font-lock has all its stuff abstracted into buffer
>> local function variables, I am not sure if I can count it is not nil?
>
> But it's no buffer-local variable, it's a function.  If you have emacs
> 25.1 upwards, you have `font-lock-ensure'.
>
>> If I can I would gladly remove the check. I appreciate advice, I am
>> not so familiar with all the details of everything.
>
> I think that's a common check for 3rd-party packages which want to keep
> supporting emacs 24.  But since you are hacking emacs core, there's no
> need for that unless the function/variable is only defined if some
> configure option is given or some lib is available.  But none of the
> latter applies to font-lock.el.

Allright, thank you. I didn't know so much about font lock :).

Re: Path & Demo: Source View in Help Buffers

[Arthur Miller]

[-- Attachment #1: Type: text/plain, Size: 1079 bytes --]

Tassilo Horn <tsdh@gnu.org> writes:

> Arthur Miller <arthur.miller@live.com> writes:
>
>>> Out of curiosity, why do you have fboundp-checks for font-lock-ensure
>>> in the code?  That's always true, isn't it?
>>
>> I don't know. Since font-lock has all its stuff abstracted into buffer
>> local function variables, I am not sure if I can count it is not nil?
>
> But it's no buffer-local variable, it's a function.  If you have emacs
> 25.1 upwards, you have `font-lock-ensure'.
>
>> If I can I would gladly remove the check. I appreciate advice, I am
>> not so familiar with all the details of everything.
>
> I think that's a common check for 3rd-party packages which want to keep
> supporting emacs 24.  But since you are hacking emacs core, there's no
> need for that unless the function/variable is only defined if some
> configure option is given or some lib is available.  But none of the
> latter applies to font-lock.el.
>

Yes, I have tested now, it works fine. I did even som minor refactoring.

Don't know if anyone else cares at all, anyway here is updated patch.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Display-source-code-in-help-mode-buffers.patch --]
[-- Type: text/x-patch, Size: 8239 bytes --]

From 63f6f0a9806c8326b8913f5d6856d841c019b4d0 Mon Sep 17 00:00:00 2001
From: Arthur Miller <arthur.miller@live.com>
Date: Wed, 22 Sep 2021 15:33:56 +0200
Subject: [PATCH] Display source code in 'help-mode' buffers

* lisp/help-mode.el (help-mode-inline-source): New option.
(help--fetch-c-src): New function.
(help--fetch-lisp-src): New function.
(help--insert-source): New function.
(help--remove-source): New function.
(help--toggle-source-view): New function.
(help-source-view): New button.
(help-make-xrefs): Check for 'help-mode-inline-source' and
call 'help--insert-source' to perform insertion when possible.
---
 lisp/help-mode.el | 152 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 147 insertions(+), 5 deletions(-)

diff --git a/lisp/help-mode.el b/lisp/help-mode.el
index 551cf7e1a3..dc6a532c63 100644
--- a/lisp/help-mode.el
+++ b/lisp/help-mode.el
@@ -149,6 +149,16 @@ help-mode-hook
   "Hook run by `help-mode'."
   :type 'hook
   :group 'help)
+
+(defcustom help-mode-inline-source nil
+  "Display inlined source code in `help-mode' buffers.
+
+When enabled the source code of a symbol currently shown in the
+help-buffer will be displayed inlined in the help buffer, if the
+source code for the symbol is available."
+  :type 'boolean
+  :group 'help
+  :version "28.1")
 \f
 ;; Button types used by help
 
@@ -367,6 +377,11 @@ 'help-news
     (view-buffer-other-window (find-file-noselect file))
     (goto-char pos))
   'help-echo (purecopy "mouse-2, RET: show corresponding NEWS announcement"))
+
+(define-button-type 'help-source-view
+  :supertype 'help-xref
+  'help-function #'help-toggle-source-view
+  'help-echo (purecopy "mouse-2, RET: toggle source view in help-buffer"))
 \f
 (defvar bookmark-make-record-function)
 (defvar help-mode--current-data nil)
@@ -503,6 +518,102 @@ describe-symbol-backends
     and a frame), inserts the description of that symbol in the current buffer
     and returns that text as well.")
 
+(defun help--fetch-c-src (symbol type file)
+  "Find C source code for a Lisp SYMBOL in a FILE.
+
+symbol - the symbol to find.
+type - the type as obtained by 'describe-*' functions.
+file - the source file to search in."
+  (let (src beg)
+    (setq file (expand-file-name file source-directory))
+    (when (file-readable-p file)
+      (with-temp-buffer
+        (insert-file-contents-literally file)
+        (delay-mode-hooks (funcall 'c-mode))
+        (goto-char (point-min))
+        (unless type
+          ;; Either or both an alias and its target might be advised.
+          (setq symbol (find-function-advised-original
+		            (indirect-function
+		             (find-function-advised-original symbol)))))
+        (when (re-search-forward
+	       (if type
+		   (concat "DEFVAR[A-Z_]*[ \t\n]*([ \t\n]*\""
+			   (regexp-quote (symbol-name symbol))
+			   "\"")
+	         (concat "DEFUN[ \t\n]*([ \t\n]*\""
+		         (regexp-quote (subr-name (advice--cd*r symbol)))
+		         "\""))
+	       nil t)
+          (if type
+              (and (re-search-backward "DEFVAR" nil t)
+                   (setq beg (point))
+                   (re-search-forward ");$" nil t))
+            (and (re-search-backward "DEFUN" nil t)
+                 (setq beg (point))
+                 (re-search-forward ")[\n\s\t\r]*{")
+                 (re-search-forward "^}[\n\s\t\r]+")))
+          (narrow-to-region beg (point))
+          (with-no-warnings (font-lock-fontify-buffer))
+          (setq src (buffer-string)))))
+    src))
+
+(defun help--fetch-lisp-src (symbol type file)
+  "Find emacs-lisp source code for a Lisp SYMBOL in a FILE.
+
+symbol - the symbol to find.
+type - the type as obtained by 'describe-*' functions.
+file - the source file to search in."
+  (let (src pos)
+    (when file
+      (setq file (or file (find-lisp-object-file-name symbol type))))
+    (with-temp-buffer
+      (insert-file-contents file)
+      (delay-mode-hooks (funcall 'emacs-lisp-mode))
+      (setq pos (cdr (find-function-search-for-symbol symbol type file)))
+      (when pos
+        (goto-char pos)
+        (forward-sexp)
+        (narrow-to-region pos (point))
+        (with-no-warnings (font-lock-fontify-buffer))
+        (setq src (buffer-string))))
+    src))
+
+(defun help--insert-source ()
+  "Fnd and insert source for the current symbol into the help-mode
+buffer."
+  (with-silent-modifications
+    (with-current-buffer (help-buffer)
+      (save-excursion
+        (let* ((file (plist-get help-mode--current-data :file))
+               (type (plist-get help-mode--current-data :type))
+               (sym (plist-get help-mode--current-data :symbol))
+               (src "Source code not available."))
+          (require 'find-func)
+          (when (eq file 'C-source)
+            (setq file (help-C-file-name (indirect-function sym) 'fun)))
+          (setq src (if (string-suffix-p ".c" file)
+                        (help--fetch-c-src sym type file)
+                      (help--fetch-lisp-src sym type file)))
+          (goto-char (point-max))
+          (let ((end (point)))
+            (when (search-backward "View Source Code:" nil t)
+              (delete-region (point) end)
+              (help-insert-xref-button "Hide Source Code:" 'help-source-view)
+              (insert (concat "\n" src "\n")))))))))
+
+(defun help--remove-source ()
+  "Remove source code from the help buffer when present."
+  (with-current-buffer (help-buffer)
+    (with-silent-modifications
+      (save-excursion
+        (goto-char (point-max))
+        (let ((end (point)))
+          (when (search-backward "Hide Source Code:" nil t)
+            (delete-region (point) end)
+            (help-insert-xref-button
+             "View Source Code:" 'help-source-view)))))))
+
 ;;;###autoload
 (defun help-make-xrefs (&optional buffer)
   "Parse and hyperlink documentation cross-references in the given BUFFER.
@@ -664,7 +775,25 @@ help-make-xrefs
             (help-insert-xref-button help-forward-label 'help-forward
                                      (current-buffer)))
           (when (or help-xref-stack help-xref-forward-stack)
-            (insert "\n")))
+            (insert "\n"))
+          (insert "\n")
+          ;; get source string if needed and available
+          ;; describe-symbol does not produce 'current-data' plist
+          (unless help-mode--current-data
+            (save-excursion
+              (goto-char (point-min))
+              (when (re-search-forward "\\.\\(el\\|c\\)" nil t)
+                (goto-char (- (point) 2))
+                (let ((props (get-text-property (point) 'help-args)))
+                  (when props
+                    (setq help-mode--current-data
+                          (list :symbol (nth 0 props)
+                                :file (nth 1 props))))))))
+          (if help-mode-inline-source
+              (progn
+                (insert "View Source Code:") ;; just a little hack
+                (help--insert-source))
+            (help-insert-xref-button "View Source Code:" 'help-source-view)))
         (set-buffer-modified-p old-modified)))))
 
 ;;;###autoload
@@ -819,10 +948,23 @@ help-do-xref
                         (append args (list (generate-new-buffer-name "*info*")))
                       args))))
 
-;; The doc string is meant to explain what buttons do.
-(defun help-follow-mouse ()
-  "Follow the cross-reference that you click on."
-  (declare (obsolete nil "28.1"))
+(defun help-toggle-source-view ()
+  "Toggle source code display in help buffer for the current symbol."
+  (interactive)
+  (when (get-buffer-window (help-buffer))
+    (with-current-buffer (help-buffer)
+      (unless (plist-get help-mode--current-data :file)
+        (error "Source file for the current help item is not defined"))
+      (save-excursion
+        (goto-char (point-min))
+        (if (search-forward "Hide Source Code:" nil t)
+            (help--remove-source)
+          (help--insert-source))))))
+
+  ;; The doc string is meant to explain what buttons do.
+  (defun help-follow-mouse ()
+    "Follow the cross-reference that you click on."
+    (declare (obsolete nil "28.1"))
   (interactive)
   (error "No cross-reference here"))
 
-- 
2.33.0

Re: Path & Demo: Source View in Help Buffers

[Tassilo Horn]

Arthur Miller <arthur.miller@live.com> writes:

>> I think that's a common check for 3rd-party packages which want to keep
>> supporting emacs 24.  But since you are hacking emacs core, there's no
>> need for that unless the function/variable is only defined if some
>> configure option is given or some lib is available.  But none of the
>> latter applies to font-lock.el.
>
> Yes, I have tested now, it works fine. I did even som minor
> refactoring.
>
> Don't know if anyone else cares at all,

I don't know either. :-)

> anyway here is updated patch.

--8<---------------cut here---------------start------------->8---
+(defun help--insert-source ()
+  "Fnd and insert source for the current symbol into the help-mode
+buffer."
--8<---------------cut here---------------end--------------->8---

Nitpick: There's an "i" missing in "F[i]nd" and checkdoc wants the first
sentence on the first line.

Aside from that, I think it would be useful if one could jump from the
shown inlined code into the source file, too.  Then one doesn't have to
navigate back to the filename.{c,el} link.  Maybe it could even jump to
the line corresponding to the location of point in the inlined code?  At
least the lines offset is easy to calculate.

Bye,
Tassilo

Re: Path & Demo: Source View in Help Buffers

[Arthur Miller]

Tassilo Horn <tsdh@gnu.org> writes:

> Arthur Miller <arthur.miller@live.com> writes:
>
>>> I think that's a common check for 3rd-party packages which want to keep
>>> supporting emacs 24.  But since you are hacking emacs core, there's no
>>> need for that unless the function/variable is only defined if some
>>> configure option is given or some lib is available.  But none of the
>>> latter applies to font-lock.el.
>>
>> Yes, I have tested now, it works fine. I did even som minor
>> refactoring.
>>
>> Don't know if anyone else cares at all,
>
> I don't know either. :-)
>
>> anyway here is updated patch.
>
> +(defun help--insert-source ()
> +  "Fnd and insert source for the current symbol into the help-mode
> +buffer."
>
> Nitpick: There's an "i" missing in "F[i]nd" and checkdoc wants the first
> sentence on the first line.
:-) Haha, thanks. Yes, I didn't notice it spilled over to next line. Will try to
reword it. It is just internal function, and function name should be enough
self-documenting for most people.

> Aside from that, I think it would be useful if one could jump from the
> shown inlined code into the source file, too.  Then one doesn't have to
> navigate back to the filename.{c,el} link.  Maybe it could even jump to
> the line corresponding to the location of point in the inlined code?  At
> least the lines offset is easy to calculate.

I know; I was thinking of that one, but it will have to be at some other time if
at all. It is not difficult to do at all, but I don't want to spend more time on
the patch if it's not interesting to include it.