[elpa] externals/dash b0ff280 205/426: Updating docs--signature to handle aliases and subrs

[Phillip Lord]

branch: externals/dash
commit b0ff280894fce8b88bd41d12607fb497b2c72590
Author: Wilfred Hughes <address@hidden>
Commit: Wilfred Hughes <address@hidden>

    Updating docs--signature to handle aliases and subrs
    
    I've also removed docs--docstring since it's just 'documentation.
---
 README.md               |   18 ++++++++++++++++++
 dev/examples-to-docs.el |   36 +++++++++++++++++++++++++-----------
 2 files changed, 43 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 51209ae..8750a11 100644
--- a/README.md
+++ b/README.md
@@ -12,6 +12,8 @@ Or you can just dump `dash.el` in your load path somewhere.
 
 ## Functions
 
+* [-first-item](#-first-item-list) `(list)`
+* [-last-item](#-last-item-list) `(list)`
 * [-map](#-map-fn-list) `(fn list)`
 * [-reduce-from](#-reduce-from-fn-initial-value-list) `(fn initial-value list)`
 * [-reduce-r-from](#-reduce-r-from-fn-initial-value-list) `(fn initial-value 
list)`
@@ -106,6 +108,22 @@ which demonstrates the usefulness of both versions.
 
 ## Documentation and examples
 
+### -first-item `(list)`
+
+Returns the first item of `list`, or nil on an empty list.
+
+```cl
+(-first-item '(1 2 3)) ;; => 1
+```
+
+### -last-item `(list)`
+
+Returns the first item of `list`, or nil on an empty list.
+
+```cl
+(-last-item '(1 2 3)) ;; => 3
+```
+
 ### -map `(fn list)`
 
 Returns a new list consisting of the result of applying `fn` to the items in 
`list`.
diff --git a/dev/examples-to-docs.el b/dev/examples-to-docs.el
index 4b40b38..a5be5d3 100644
--- a/dev/examples-to-docs.el
+++ b/dev/examples-to-docs.el
@@ -1,4 +1,5 @@
 (require 'dash)
+(require 'help-fns)
 
 (defvar functions '())
 
@@ -11,21 +12,34 @@
       (replace-regexp-in-string "\t" "\\t" it t t)
       (replace-regexp-in-string "\r" "\\r" it t t))))
 
-(defun docs--signature (cmd)
-  (if (eq 'macro (car cmd))
-      (nth 2 cmd)
-    (nth 1 cmd)))
-
-(defun docs--docstring (cmd)
-  (if (eq 'macro (car cmd))
-      (nth 3 cmd)
-    (nth 2 cmd)))
+(defun docs--signature (function)
+  "Given FUNCTION (a symbol), return its argument list.
+FUNCTION may reference an elisp function, alias, macro or a subr."
+  (let* ((function-value (indirect-function function))
+         (is-alias (eq function-value (symbol-function function)))
+         ;; if FUNCTION isn't an alias, function-symbol is simply FUNCTION
+         (function-symbol function))
+    
+    (when is-alias
+      ;; find the last symbol in the alias chain
+      (while (symbolp (symbol-function function-symbol))
+        (setq function-symbol (symbol-function function-symbol))))
+    
+    (if (subrp function-value)
+        ;; read the docstring to find the signature for subrs
+        (let* ((docstring-args (car (help-split-fundoc
+                                     (documentation function-value)
+                                     function-symbol)))
+               (fun-with-args (read (downcase docstring-args))))
+          (cdr fun-with-args))
+      ;; otherwise get the signature directly
+      (help-function-arglist function-symbol))))
 
 (defmacro defexamples (cmd &rest examples)
   `(add-to-list 'functions (list
                             ',cmd
-                            (docs--signature (symbol-function ',cmd))
-                            (docs--docstring (symbol-function ',cmd))
+                            (docs--signature ',cmd)
+                            (documentation ',cmd)
                             (-map 'example-to-string (-partition 3 
',examples)))))
 
 (defun quote-and-downcase (string)