helpful

commit 0d87632274b5713763dc96a912fffde0b1c0032c
parent d905694711de8ce0c98859850cfe5f30052f55c4
Author: Wilfred Hughes <me@wilfred.me.uk>
Date:   Sun,  2 Apr 2017 11:42:27 +0100

Basic docstring extraction

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

2 files changed, 60 insertions(+), 6 deletions(-)
diff --git a/helpful.el b/helpful.el
@@ -5,6 +5,7 @@
 ;; Author: Wilfred Hughes <me@wilfred.me.uk>
 ;; Keywords: help, lisp
 ;; Version: 0.1
+;; Package-Requires: ((dash "2.12.0") (s "1.11.0"))
 
 ;; This program is free software; you can redistribute it and/or modify
 ;; it under the terms of the GNU General Public License as published by
@@ -25,6 +26,10 @@
 
 ;;; Code:
 
+(require 'help)
+(require 'dash)
+(require 's)
+
 (defvar-local helpful--sym nil)
 
 (defun helpful--buffer (symbol)
@@ -45,15 +50,35 @@ state of the current symbol."
     (erase-buffer)
     (insert
      (format "Symbol: %s\n\n" helpful--sym)
-     "Documentation\n\n")
+     "Documentation\n"
+     (helpful--docstring helpful--sym))
     (goto-char start-pos)))
 
+(defun helpful--skip-advice (docstring)
+  "Remove mentions of advice from DOCSTRING."
+  (let* ((lines (s-lines docstring))
+         (relevant-lines
+          (--drop-while (s-starts-with-p ":around advice:" it) lines)))
+    (s-trim (s-join "\n" relevant-lines))))
+
+(defun helpful--docstring (sym)
+  "Get the docstring for SYM."
+  (let* ((docstring (documentation sym))
+         (docstring-with-usage (help-split-fundoc docstring sym)))
+    (when docstring-with-usage
+      (setq docstring (cdr docstring-with-usage))
+      ;; Advice mutates the docstring, see
+      ;; `advice--make-docstring'. Undo that.
+      ;; TODO: Only do this if the function is adviced.
+      (setq docstring (helpful--skip-advice docstring)))
+    docstring))
+
 (defun helpful (symbol)
   "Show Help for SYMBOL."
   (interactive
-   (list (completing-read "Symbol: " obarray
-                          nil nil nil nil
-                          (symbol-name (symbol-at-point)))))
+   (list (read (completing-read "Symbol: " obarray
+                                nil nil nil nil
+                                (symbol-name (symbol-at-point))))))
   (switch-to-buffer (helpful--buffer symbol))
   (helpful-update))
 
diff --git a/test/unit-test.el b/test/unit-test.el
@@ -1,4 +1,33 @@
 (require 'ert)
+(require 'helpful)
+
+(defun test-foo ()
+  "Docstring here."
+  nil)
+
+(defun test-foo-advised ()
+  "Docstring here too."
+  nil)
+
+(defadvice test-foo-advised (before test-advice1 activate)
+  "Placeholder advice 1."
+  nil)
+
+(defadvice test-foo-advised (after test-advice2 activate)
+  "Placeholder advice 2."
+  nil)
+
+(ert-deftest helpful--docstring ()
+  "Basic docstring fetching."
+  (should
+   (equal
+    (helpful--docstring #'test-foo)
+    "Docstring here.")))
+
+(ert-deftest helpful--docstring-advice ()
+  "Get the docstring on advised functions."
+  (should
+   (equal
+    (helpful--docstring #'test-foo-advised)
+    "Docstring here too.")))
 
-(ert-deftest dummy-test ()
-  (should (equal 1 1)))