Updating docs--signature to handle aliases and subrs

I've also removed docs--docstring since it's just 'documentation.

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`.

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)
+(defun docs--signature (function)
-  (if (eq 'macro (car cmd))
+  "Given FUNCTION (a symbol), return its argument list.
-      (nth 2 cmd)
+FUNCTION may reference an elisp function, alias, macro or a subr."
-    (nth 1 cmd)))
+  (let* ((function-value (indirect-function function))
-
+         (is-alias (eq function-value (symbol-function function)))
-(defun docs--docstring (cmd)
+         ;; if FUNCTION isn't an alias, function-symbol is simply FUNCTION
-  (if (eq 'macro (car cmd))
+         (function-symbol function))
-      (nth 3 cmd)
+    
-    (nth 2 cmd)))
+    (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--signature ',cmd)
-                            (docs--docstring (symbol-function ',cmd))
+                            (documentation ',cmd)
                             (-map 'example-to-string (-partition 3 ',examples)))))
 
 (defun quote-and-downcase (string)