Load signature from functions that (declare ...) the signature

Fixes #104.

3 files changed, 30 insertions, 6 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 073aa99..0355c46 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 URLs in docstrings are now converted to buttons.
 
+Function signatures are now correct when a function uses
+`(declare (advertised-calling-convention ...))`.
+
 # v0.9
 
 Much better handling of aliases: show aliases differently to their
diff --git a/helpful.el b/helpful.el
index b775f7c..7154e14 100644
--- a/helpful.el
+++ b/helpful.el
@@ -1651,17 +1651,23 @@ state of the current symbol."
   "Get the signature for function SYM, as a string.
 For example, \"(some-func FOO &optional BAR)\"."
   (let (docstring-sig
-        source-sig)
+        source-sig
+        (advertised-args
+         (when (symbolp sym)
+           (gethash (symbol-function sym) advertised-signature-table))))
     ;; Get the usage from the function definition.
     (let* ((function-args
             (if (symbolp sym)
                 (help-function-arglist sym)
               (cadr sym)))
            (formatted-args
-            (if (listp function-args)
-                (-map #'helpful--format-argument
-                      function-args)
-              (list function-args))))
+            (cond
+             (advertised-args
+              (-map #'helpful--format-argument advertised-args))
+             ((listp function-args)
+              (-map #'helpful--format-argument function-args))
+             (t
+              (list function-args)))))
       (setq source-sig
             (cond
              ;; If it's a function object, just show the arguments.
@@ -1681,7 +1687,16 @@ For example, \"(some-func FOO &optional BAR)\"."
       (-when-let (docstring-with-usage (help-split-fundoc docstring sym))
         (setq docstring-sig (car docstring-with-usage))))
 
-    (or docstring-sig source-sig)))
+    (cond
+     ;; Advertised signature always wins.
+     (advertised-args
+      source-sig)
+     ;; If that's not set, use the usage specification in the
+     ;; docstring, if present.
+     (docstring-sig)
+     (t
+      ;; Otherwise, just use the signature from the source code.
+      source-sig))))
 
 (defun helpful--docstring (sym callable-p)
   "Get the docstring for SYM.
diff --git a/test/unit-test.el b/test/unit-test.el
index 99eb5af..4ec999a 100644
--- a/test/unit-test.el
+++ b/test/unit-test.el
@@ -311,6 +311,12 @@ variables defined without `defvar'."
    (equal (helpful--signature 'some-unused-function)
           "(some-unused-function [Arg list not available until function definition is loaded.])")))
 
+(ert-deftest helpful--signature--advertised ()
+  "Ensure that we respect functions that declare `advertised-calling-convention'."
+  (should
+   (equal (helpful--signature 'start-process-shell-command)
+          "(start-process-shell-command NAME BUFFER COMMAND)")))
+
 (ert-deftest helpful-function--single-buffer ()
   "Ensure that calling `helpful-buffer' does not leave any extra
 buffers lying around."