helpful

commit 00c5c696521dd361e540af8a1fb5c529527ab5cb
parent 866d5daecb168c0b62c91ccf5dec833d5cdcac5c
Author: Wilfred Hughes <me@wilfred.me.uk>
Date:   Wed, 24 Jul 2019 00:39:22 +0100

Report package/emacs version for custom variables

Fixes #207

Diffstat:
M
CHANGELOG.md
 | 
2
++
M
helpful.el
 | 
41
+++++++++++++++++++++++++++++++++--------
M
test/helpful-unit-test.el
 | 
13
++++++++++++-

3 files changed, 47 insertions(+), 9 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 Show the original value for custom variables whose value has changed.
 
+Report the package version when custom variables were added.
+
 # v0.17
 
 Fixed a minor docstring formatting issue when keymap references were
diff --git a/helpful.el b/helpful.el
@@ -1234,6 +1234,25 @@ If the source code cannot be found, return the sexp used."
     (or (assoc sym completions)
         (assoc-string sym completions))))
 
+(defun helpful--version-info (sym)
+  "If SYM has version information, format and return it.
+Return nil otherwise."
+  (when (symbolp sym)
+    (let ((package-version
+           (get sym 'custom-package-version))
+          (emacs-version
+           (get sym 'custom-version)))
+      (cond
+       (package-version
+        (format
+         "This variable was added, or its default value changed, in %s version %s."
+         (car package-version)
+         (cdr package-version)))
+       (emacs-version
+        (format
+         "This variable was added, or its default value changed, in Emacs %s."
+         emacs-version))))))
+
 (defun helpful--library-path (library-name)
   "Find the absolute path for the source of LIBRARY-NAME.
 
@@ -2154,14 +2173,20 @@ state of the current symbol."
         (when (custom-variable-p helpful--sym)
           (insert " " (helpful--make-customize-button helpful--sym)))))
 
-    (-when-let (docstring (helpful--docstring helpful--sym helpful--callable-p))
-      (helpful--insert-section-break)
-      (insert
-       (helpful--heading "Documentation")
-       (helpful--format-docstring docstring))
-      (when (helpful--in-manual-p helpful--sym)
-        (insert "\n\n")
-        (insert (helpful--make-manual-button helpful--sym))))
+    (let ((docstring (helpful--docstring helpful--sym helpful--callable-p))
+          (version-info (unless helpful--callable-p
+                          (helpful--version-info helpful--sym))))
+      (when (or docstring version-info)
+        (helpful--insert-section-break)
+        (insert
+         (helpful--heading "Documentation"))
+        (when docstring
+          (insert (helpful--format-docstring docstring)))
+        (when version-info
+          (insert "\n\n" (s-word-wrap 70 version-info)))
+        (when (helpful--in-manual-p helpful--sym)
+          (insert "\n\n")
+          (insert (helpful--make-manual-button helpful--sym)))))
 
     ;; Show keybindings.
     ;; TODO: allow users to conveniently add and remove keybindings.
diff --git a/test/helpful-unit-test.el b/test/helpful-unit-test.el
@@ -954,7 +954,8 @@ find the source code."
 (defcustom helpful-test-custom-var 123
   "I am an example custom variable."
   :type 'number
-  :group 'helpful)
+  :group 'helpful
+  :package-version '(helpful . "1.2.3"))
 
 ;; Ensure the current value differs from the original value.
 (setq helpful-test-custom-var 456)
@@ -964,3 +965,13 @@ find the source code."
   (helpful-variable 'helpful-test-custom-var)
   (should
    (s-contains-p "Original Value\n123" (buffer-string))))
+
+(ert-deftest helpful--package-version ()
+  "Report when a variable was added"
+  (helpful-variable 'helpful-test-custom-var)
+  (should
+   (s-contains-p
+    (s-word-wrap
+     70
+     "This variable was added, or its default value changed, in helpful version 1.2.3.")
+    (buffer-string))))