branch: externals/dash
commit 3c608b1331a65449a7702c788eb1cb2e9f04ef8e
Author: Basil L. Contovounesios <ba...@contovou.net>
Commit: Basil L. Contovounesios <ba...@contovou.net>
Update stable docstrings for aliases
* dash.el (-concat, -copy): Include more/latest details from
upstream docstrings.
(-partial): Give it a stable docstring based on that of
apply-partially to avoid churn/annoyances for Dash developers.
* README.md:
* dash.texi: Regenerate docs.
---
README.md | 10 ++++++++--
dash.el | 23 +++++++++++++++++------
dash.texi | 10 ++++++++--
3 files changed, 33 insertions(+), 10 deletions(-)
diff --git a/README.md b/README.md
index 83e15c0eb9..9fd73c4a08 100644
--- a/README.md
+++ b/README.md
@@ -520,6 +520,7 @@ Thus function `fn` should return a list.
#### -copy `(list)`
Create a shallow copy of `list`.
+The elements of `list` are not copied; they are shared with the original.
```el
(-copy '(1 2 3)) ;; => (1 2 3)
@@ -791,12 +792,17 @@ Its anaphoric counterpart is `--keep`.
#### -concat `(&rest sequences)`
-Concatenate all the arguments and make the result a list.
+Concatenate all `sequences` and make the result a list.
The result is a list whose elements are the elements of all the arguments.
Each argument may be a list, vector or string.
All arguments except the last argument are copied. The last argument
-is just used as the tail of the new list.
+is just used as the tail of the new list. If the last argument is not
+a list, this results in a dotted list.
+
+As an exception, if all the arguments except the last are `nil`, and the
+last argument is not a list, the return value is that last argument
+unaltered, not a list.
```el
(-concat '(1)) ;; => (1)
diff --git a/dash.el b/dash.el
index ea70a72dca..b1aa2c6bf1 100644
--- a/dash.el
+++ b/dash.el
@@ -793,19 +793,24 @@ See also: `-flatten'"
list)
(defalias '-concat #'append
- "Concatenate all the arguments and make the result a list.
+ "Concatenate all SEQUENCES and make the result a list.
The result is a list whose elements are the elements of all the arguments.
Each argument may be a list, vector or string.
All arguments except the last argument are copied. The last argument
-is just used as the tail of the new list.
+is just used as the tail of the new list. If the last argument is not
+a list, this results in a dotted list.
+
+As an exception, if all the arguments except the last are nil, and the
+last argument is not a list, the return value is that last argument
+unaltered, not a list.
\(fn &rest SEQUENCES)")
(defalias '-copy #'copy-sequence
"Create a shallow copy of LIST.
-
-\(fn LIST)")
+The elements of LIST are not copied; they are shared with the original.
+\n(fn LIST)")
(defmacro --splice (pred form list)
"Splice lists generated by FORM in place of items satisfying PRED in LIST.
@@ -2460,7 +2465,7 @@ Similar to &hash but check whether the map is not nil."
`(let ((,src ,source))
(when ,src (gethash ,key ,src)))))
-(defalias 'dash-expand:&keys 'dash-expand:&plist)
+(defalias 'dash-expand:&keys #'dash-expand:&plist)
(defun dash--match-kv-1 (match-form source type)
"Match MATCH-FORM against SOURCE of type TYPE.
@@ -3654,7 +3659,13 @@ structure such as plist or alist."
;;; Combinators
-(defalias '-partial #'apply-partially)
+(defalias '-partial #'apply-partially
+ "Return a function that is a partial application of FUN to ARGS.
+ARGS is a list of the first N arguments to pass to FUN.
+The result is a new function which does the same as FUN, except that
+the first N arguments are fixed at the values with which this function
+was called.
+\n(fn FUN &rest ARGS)")
(defun -rpartial (fn &rest args)
"Return a function that is a partial application of FN to ARGS.
diff --git a/dash.texi b/dash.texi
index 4c9d07c8aa..bc46537ac9 100644
--- a/dash.texi
+++ b/dash.texi
@@ -463,6 +463,7 @@ Thus function @var{fn} should return a list.
@anchor{-copy}
@defun -copy (list)
Create a shallow copy of @var{list}.
+The elements of @var{list} are not copied; they are shared with the original.
@example
@group
@@ -907,12 +908,17 @@ Its anaphoric counterpart is @code{--keep}.
@anchor{-concat}
@defun -concat (&rest sequences)
-Concatenate all the arguments and make the result a list.
+Concatenate all @var{sequences} and make the result a list.
The result is a list whose elements are the elements of all the arguments.
Each argument may be a list, vector or string.
All arguments except the last argument are copied. The last argument
-is just used as the tail of the new list.
+is just used as the tail of the new list. If the last argument is not
+a list, this results in a dotted list.
+
+As an exception, if all the arguments except the last are @code{nil}, and the
+last argument is not a list, the return value is that last argument
+unaltered, not a list.
@example
@group
