helpful

commit dcf0b2fc030675a6030e458a927d74025a954122
parent e30bcc2c1a1408aa39838590a2d4a8b1899b09b3
Author: Nathan Moreau <nathan.moreau@m4x.org>
Date:   Tue, 18 Dec 2018 20:56:34 +0100

Add obsolescence information.

helpful.el (helpful--obsolete-info): new function.
(helpful--format-alias): obsolescence info code extracted.
(helpful-update): display the obsolescence info.
(helpful--format-obsolete-info): new function.

Closes #152.

Diffstat:
M
helpful.el
 | 
30
+++++++++++++++++++++++++++---
M
test/helpful-unit-test.el
 | 
15
+++++++++++++++

2 files changed, 42 insertions(+), 3 deletions(-)
diff --git a/helpful.el b/helpful.el
@@ -152,6 +152,10 @@ can make Helpful very slow.")
   "Propertize TEXT as a heading."
   (format "%s\n" (propertize text 'face 'helpful-heading)))
 
+(defun helpful--warning (text)
+  "Propertize TEXT as a warning."
+  (format "%s\n" (propertize text 'face 'warning)))
+
 (defun helpful--format-closure (sym form)
   "Given a closure, return an equivalent defun form."
   (-let (((_keyword _env args . body) form)
@@ -233,10 +237,12 @@ Return SYM otherwise."
          (push s aliases))))
     (helpful--sort-symbols aliases)))
 
+(defun helpful--obsolete-info (sym callable-p)
+  (when (symbolp sym)
+    (get sym (if callable-p 'byte-obsolete-info 'byte-obsolete-variable))))
+
 (defun helpful--format-alias (sym callable-p)
-  (let ((obsolete-info (if callable-p
-                           (get sym 'byte-obsolete-info)
-                         (get sym 'byte-obsolete-variable)))
+  (let ((obsolete-info (helpful--obsolete-info sym callable-p))
         (sym-button (helpful--button
                      (symbol-name sym)
                      'helpful-describe-exactly-button
@@ -1862,6 +1868,11 @@ state of the current symbol."
 
     (insert (helpful--summary helpful--sym helpful--callable-p buf pos))
 
+    (when (helpful--obsolete-info helpful--sym helpful--callable-p)
+      (insert
+       "\n\n"
+       (helpful--format-obsolete-info helpful--sym helpful--callable-p)))
+
     (when (and helpful--callable-p
 	           (not (helpful--kbd-macro-p helpful--sym)))
       (helpful--insert-section-break)
@@ -2174,6 +2185,19 @@ For example, \"(some-func FOO &optional BAR)\"."
       ;; Otherwise, just use the signature from the source code.
       source-sig))))
 
+(defun helpful--format-obsolete-info (sym callable-p)
+  (-let [(use _ date) (helpful--obsolete-info sym callable-p)]
+    (helpful--propertize-quoted
+     (s-word-wrap
+      70
+      (format "This %s is obsolete%s%s"
+	      (helpful--kind-name sym callable-p)
+	      (if date (format " since %s" date)
+	        "")
+	      (cond ((stringp use) (concat "; " use))
+    		    (use (format "; use `%s' instead." use))
+    		    (t ".")))))))
+
 (defun helpful--docstring (sym callable-p)
   "Get the docstring for SYM.
 Note that this returns the raw docstring, including \\=\\=
diff --git a/test/helpful-unit-test.el b/test/helpful-unit-test.el
@@ -457,6 +457,21 @@ associated a lambda with a keybinding."
     (with-current-buffer buf
       (helpful-update))))
 
+(ert-deftest helpful--obsolete-variable ()
+  "Test display of obsolete variable."
+  (let* ((var 'bookmark-read-annotation-text-func)
+         (info (helpful--format-obsolete-info var nil)))
+    (should
+     (equal info "This variable is obsolete since 23.1;
+use bookmark-edit-annotation-text-func instead."))))
+
+(ert-deftest helpful--obsolete-function ()
+  "Test display of obsolete function."
+  (let* ((fun 'ffap-submit-bug)
+         (info (helpful--format-obsolete-info fun t)))
+    (should
+     (equal info "This command is obsolete since 23.1; use report-emacs-bug instead."))))
+
 (ert-deftest helpful--keymap-keys--sparse ()
   (let* ((parent-keymap (make-sparse-keymap))
          (keymap (make-sparse-keymap)))