[elpa] externals/dash 5362be7 275/316: Use actual advertised function signature in manual

[ELPA Syncer]

branch: externals/dash
commit 5362be78c437a722e2f76f9dfcfccd99446c1cf9
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>

    Use actual advertised function signature in manual
    
    This is a copy of commit 2aeb4e4f354afe7224e755ccb3a6b2c7d4d09428 of
    2021-01-18 "Use actual advertised function signature in README".
    
    * dev/examples-to-info.el (docs--signature): Remove function.
    (dash--describe): New function using the same machinery as
    describe-function to determine arglists and docstrings.
    (defexamples): Use it instead of docs--signature.
    
    * dash.texi: Regenerate.
---
 dash.texi               | 34 ++++++++--------------------------
 dev/examples-to-info.el | 44 ++++++++++++++++++--------------------------
 2 files changed, 26 insertions(+), 52 deletions(-)

diff --git a/dash.texi b/dash.texi
index 9a05cb8..440eb6f 100644
--- a/dash.texi
+++ b/dash.texi
@@ -460,11 +460,9 @@ Thus function @var{fn} should return a list.
 @end defun
 
 @anchor{-copy}
-@defun -copy (arg)
+@defun -copy (list)
 Create a shallow copy of @var{list}.
 
-(fn @var{list})
-
 @example
 @group
 (-copy '(1 2 3))
@@ -584,12 +582,10 @@ See also @code{-map-last} (@pxref{-map-last}), 
@code{-remove-item} (@pxref{-remo
 @end defun
 
 @anchor{-remove-item}
-@defun -remove-item (arg1 arg2)
+@defun -remove-item (item list)
 Return a copy of @var{list} with all occurrences of @var{item} removed.
 The comparison is done with @code{equal}.
 
-(fn @var{item} @var{list})
-
 @example
 @group
 (-remove-item 3 '(1 2 3 2 3 4 5 3))
@@ -707,8 +703,6 @@ Return nil if @var{list} contains @var{n} items or fewer.
 Return @var{list} if @var{n} is zero or less.
 For another variant, see also @code{-drop-last} (@pxref{-drop-last}).
 
-(fn @var{n} @var{list})
-
 @example
 @group
 (-drop 3 '(1 2 3 4 5))
@@ -3059,8 +3053,6 @@ Return the first item of @var{list}, or nil on an empty 
list.
 
 See also: @code{-second-item} (@pxref{-second-item}), @code{-last-item} 
(@pxref{-last-item}).
 
-(fn @var{list})
-
 @example
 @group
 (-first-item '(1 2 3))
@@ -3078,13 +3070,11 @@ See also: @code{-second-item} (@pxref{-second-item}), 
@code{-last-item} (@pxref{
 @end defun
 
 @anchor{-second-item}
-@defun -second-item (arg1)
+@defun -second-item (list)
 Return the second item of @var{list}, or nil if @var{list} is too short.
 
 See also: @code{-third-item} (@pxref{-third-item}).
 
-(fn @var{list})
-
 @example
 @group
 (-second-item '(1 2 3))
@@ -3098,13 +3088,11 @@ See also: @code{-third-item} (@pxref{-third-item}).
 @end defun
 
 @anchor{-third-item}
-@defun -third-item (arg1)
+@defun -third-item (list)
 Return the third item of @var{list}, or nil if @var{list} is too short.
 
 See also: @code{-fourth-item} (@pxref{-fourth-item}).
 
-(fn @var{list})
-
 @example
 @group
 (-third-item '(1 2 3))
@@ -3217,7 +3205,7 @@ if the first element should sort before the second.
 @end defun
 
 @anchor{-list}
-@defun -list (&optional arg &rest args)
+@defun -list (arg)
 Ensure @var{arg} is a list.
 If @var{arg} is already a list, return it as is (not a copy).
 Otherwise, return a new list with @var{arg} as its only element.
@@ -3655,13 +3643,11 @@ Convenient versions of `let` and `let*` constructs 
combined with flow control.
 
 
 @anchor{-when-let}
-@defmac -when-let (var-val &rest body)
+@defmac -when-let ((var val) &rest body)
 If @var{val} evaluates to non-nil, bind it to @var{var} and execute body.
 
 Note: binding is done according to @code{-let} (@pxref{-let}).
 
-(fn (@var{var} @var{val}) &rest @var{body})
-
 @example
 @group
 (-when-let (match-index (string-match "d" "abcd")) (+ match-index 2))
@@ -3701,14 +3687,12 @@ encountered.
 @end defmac
 
 @anchor{-if-let}
-@defmac -if-let (var-val then &rest else)
+@defmac -if-let ((var val) then &rest else)
 If @var{val} evaluates to non-nil, bind it to @var{var} and do @var{then},
 otherwise do @var{else}.
 
 Note: binding is done according to @code{-let} (@pxref{-let}).
 
-(fn (@var{var} @var{val}) @var{then} &rest @var{else})
-
 @example
 @group
 (-if-let (match-index (string-match "d" "abc")) (+ match-index 3) 7)
@@ -3989,7 +3973,7 @@ See @code{-let} (@pxref{-let}) for a description of the 
destructuring mechanism.
 @end defmac
 
 @anchor{-setq}
-@defmac -setq (&rest forms)
+@defmac -setq ([match-form val] ...)
 Bind each @var{match-form} to the value of its @var{val}.
 
 @var{match-form} destructuring is done according to the rules of @code{-let} 
(@pxref{-let}).
@@ -4009,8 +3993,6 @@ expands roughly speaking to the following code
 Care is taken to only evaluate each @var{val} once so that in case of
 multiple assignments it does not cause unexpected side effects.
 
-(fn [@var{match-form} @var{val}]@dots{})
-
 @example
 @group
 (let (a) (-setq a 1) a)
diff --git a/dev/examples-to-info.el b/dev/examples-to-info.el
index 67de701..85d7c46 100644
--- a/dev/examples-to-info.el
+++ b/dev/examples-to-info.el
@@ -50,34 +50,26 @@
        (lambda (s) (concat "\\" (text-char-description (string-to-char s))))
        it t t))))
 
-(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 (not (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))))
+(defun dash--describe (fn)
+  "Return the (ARGLIST DOCSTRING) of FN symbol.
+Based on `describe-function-1'."
+  (with-temp-buffer
+    (pcase-let* ((`(,real-fn ,def ,_alias ,real-def)
+                  (help-fns--analyze-function fn))
+                 (buf (current-buffer))
+                 (doc-raw (documentation fn t))
+                 (doc (help-fns--signature fn doc-raw real-def real-fn buf)))
+      (goto-char (1+ (point-min)))
+      (delete-region (point) (progn (forward-sexp) (1+ (point))))
+      (downcase-region (point) (point-max))
+      (backward-char)
+      (list (read buf) doc))))
 
 (defmacro defexamples (cmd &rest examples)
-  `(push (list ',cmd
-               (docs--signature ',cmd)
-               (documentation ',cmd)
-               (mapcar #'example-to-string (-partition 3 ',examples)))
+  `(push (cons ',cmd
+               (nconc (dash--describe ',cmd)
+                      (list (mapcar #'example-to-string
+                                    (-partition 3 ',examples)))))
          functions))
 
 (defmacro def-example-group (group desc &rest examples)