From 5b7c14242c1efad6d5ab05bf159ae0a5b7f41c32 Mon Sep 17 00:00:00 2001
From: Jens Schmidt <jschmidt4gnu@vodafonemail.de>
Date: Sat, 16 Sep 2023 14:53:18 +0200
Subject: [PATCH] Improve documentation of advised macros or functions

* lisp/emacs-lisp/nadvice.el (advice--make-single-doc): Inline advice
documentation where possible.
(advice--make-docstring): Add a prominent marker that the macro or
function is advised.
---
 lisp/emacs-lisp/nadvice.el | 47 +++++++++++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 11 deletions(-)

diff --git a/lisp/emacs-lisp/nadvice.el b/lisp/emacs-lisp/nadvice.el
index cd80df2c41d..f04a584cf74 100644
--- a/lisp/emacs-lisp/nadvice.el
+++ b/lisp/emacs-lisp/nadvice.el
@@ -93,17 +93,30 @@ advice--make-single-doc
      (format "This %s has %s advice: "
              (if macrop "macro" "function")
              how)
-     (let ((fun (advice--car flist)))
-       (if (symbolp fun) (format-message "`%S'." fun)
-         (let* ((name (cdr (assq 'name (advice--props flist))))
-                (doc (documentation fun t))
-                (usage (help-split-fundoc doc function)))
-           (if usage (setq doc (cdr usage)))
-           (if name
-               (if doc
-                   (format "%s\n%s" name doc)
-                 (format "%s" name))
-             (or doc "No documentation")))))
+     (let* ((fun (advice--car flist))
+            (doc (documentation fun t))
+            (usage (help-split-fundoc doc function))
+            name)
+       (if usage (setq doc (cdr usage)))
+       (if (symbolp fun)
+           (if doc
+               (concat
+                (format-message "`%S'\n" fun)
+                ;; Remove first line possibly added by
+                ;; `ad-make-single-advice-docstring' for
+                ;; legacy advices.
+                (if (string-match
+                     "^\\(?:Before\\|Around\\|After\\)-advice `.*?':\n"
+                     doc)
+                    (substring doc (match-end 0))
+                  doc))
+             (format-message "`%S'." fun))
+         (setq name (cdr (assq 'name (advice--props flist))))
+         (if name
+             (if doc
+                 (format "%s\n%s" name doc)
+               (format "%s" name))
+           (or doc "No documentation"))))
      "\n"
      (and
       (eq how :override)
@@ -155,10 +168,22 @@ advice--make-docstring
       (help-add-fundoc-usage
        (with-temp-buffer
          (when before
+           (insert
+            (propertize
+             (concat "This " (if macrop "macro" "function") " is advised.")
+             'face 'font-lock-warning-face))
+           (ensure-empty-lines 1)
            (insert before)
            (ensure-empty-lines 1))
          (when origdoc
            (insert origdoc))
+         (when (not before)
+           (ensure-empty-lines 1)
+           (insert
+            (propertize
+             (concat "This " (if macrop "macro" "function") " is advised.")
+             'face 'font-lock-warning-face))
+           (ensure-empty-lines 1))
          (when after
            (ensure-empty-lines 1)
            (insert after))
-- 
2.30.2