[elpa] externals/dash ffe72fb 08/14: Update documentation.

[Phillip Lord]

branch: externals/dash
commit ffe72fbee0854657423ca6d9fc0fd86324069bfc
Author: Matus Goljer <address@hidden>
Commit: Matus Goljer <address@hidden>

    Update documentation.
---
 README.md |   26 +++++++++++++-----
 dash.texi |   87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 100 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 232d6bb..d66447b 100644
--- a/README.md
+++ b/README.md
@@ -598,6 +598,14 @@ Return a new list with the concatenation of the elements 
in the supplied `lists`
 
 Take a nested list `l` and return its contents as a single, flat list.
 
+Note that because `nil` represents a list of zero elements (an
+empty list), any mention of nil in `l` will disappear after
+flattening.  If you need to preserve nils, consider 
[`-flatten-n`](#-flatten-n-num-list)
+or map them to some unique symbol and then map them back.
+
+Conses of two atoms are considered "terminals", that is, they
+aren't flattened further.
+
 See also: [`-flatten-n`](#-flatten-n-num-list)
 
 ```el
@@ -1787,7 +1795,7 @@ and when that result is non-nil, through the next form, 
etc.
 ```el
 (-some-> '(2 3 5)) ;; => '(2 3 5)
 (-some-> 5 square) ;; => 25
-(-some-> nil square) ;; => nil
+(-some-> 5 even? square) ;; => nil
 ```
 
 #### -some->> `(x &optional form &rest more)`
@@ -1837,7 +1845,9 @@ If all `vals` evaluate to true, bind them to their 
corresponding
 `vars` and execute body. `vars-vals` should be a list of (`var` `val`)
 pairs.
 
-Note: binding is done according to [`-let*`](#-let-varlist-rest-body).
+Note: binding is done according to [`-let*`](#-let-varlist-rest-body).  `vals` 
are evaluated
+sequentially, and evaluation stops after the first nil `val` is
+encountered.
 
 ```el
 (-when-let* ((x 5) (y 3) (z (+ y 4))) (+ x y z)) ;; => 15
@@ -1862,7 +1872,9 @@ If all `vals` evaluate to true, bind them to their 
corresponding
 `vars` and do `then`, otherwise do `else`. `vars-vals` should be a list
 of (`var` `val`) pairs.
 
-Note: binding is done according to [`-let*`](#-let-varlist-rest-body).
+Note: binding is done according to [`-let*`](#-let-varlist-rest-body).  `vals` 
are evaluated
+sequentially, and evaluation stops after the first nil `val` is
+encountered.
 
 ```el
 (-if-let* ((x 5) (y 3) (z 7)) (+ x y z) "foo") ;; => 15
@@ -1932,10 +1944,10 @@ Vectors:
                      If the `pattern` is longer than `source`, an `error` is
                      thrown.
 
-    [a1 a2 a3 ... &rest rest] ) - as above, but bind the rest of
-                                  the sequence to `rest`.  This is
-                                  conceptually the same as improper list
-                                  matching (a1 a2 ... aN . rest)
+    [a1 a2 a3 ... &rest rest] - as above, but bind the rest of
+                                the sequence to `rest`.  This is
+                                conceptually the same as improper list
+                                matching (a1 a2 ... aN . rest)
 
 Key/value stores:
 
diff --git a/dash.texi b/dash.texi
index f566483..4e59866 100644
--- a/dash.texi
+++ b/dash.texi
@@ -727,6 +727,14 @@ Return a new list with the concatenation of the elements 
in the supplied @var{li
 @defun -flatten (l)
 Take a nested list @var{l} and return its contents as a single, flat list.
 
+Note that because @code{nil} represents a list of zero elements (an
+empty list), any mention of nil in @var{l} will disappear after
+flattening.  If you need to preserve nils, consider @code{-flatten-n} 
(@pxref{-flatten-n})
+or map them to some unique symbol and then map them back.
+
+Conses of two atoms are considered "terminals", that is, they
+aren't flattened further.
+
 See also: @code{-flatten-n} (@pxref{-flatten-n})
 
 @example
@@ -2759,6 +2767,69 @@ in second form, etc.
 @end example
 @end defun
 
address@hidden>}
address@hidden -some-> (x &optional form &rest more)
+When expr is non-nil, thread it through the first form (via @code{->} 
(@pxref{->})),
+and when that result is non-nil, through the next form, etc.
+
address@hidden
address@hidden
+(-some-> '(2 3 5))
+    @result{} '(2 3 5)
address@hidden group
address@hidden
+(-some-> 5 square)
+    @result{} 25
address@hidden group
address@hidden
+(-some-> 5 even? square)
+    @result{} nil
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden>>}
address@hidden -some->> (x &optional form &rest more)
+When expr is non-nil, thread it through the first form (via @code{->>} 
(@pxref{->>})),
+and when that result is non-nil, through the next form, etc.
+
address@hidden
address@hidden
+(-some->> '(1 2 3) (-map 'square))
+    @result{} '(1 4 9)
address@hidden group
address@hidden
+(-some->> '(1 3 5) (-last 'even?) (+ 100))
+    @result{} nil
address@hidden group
address@hidden
+(-some->> '(2 4 6) (-last 'even?) (+ 100))
+    @result{} 106
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden>}
address@hidden -some--> (x &optional form &rest more)
+When expr in non-nil, thread it through the first form (via @code{-->} 
(@pxref{-->})),
+and when that result is non-nil, through the next form, etc.
+
address@hidden
address@hidden
+(-some--> "def" (concat "abc" it "ghi"))
+    @result{} "abcdefghi"
address@hidden group
address@hidden
+(-some--> nil (concat "abc" it "ghi"))
+    @result{} nil
address@hidden group
address@hidden
+(-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it))
+    @result{} nil
address@hidden group
address@hidden example
address@hidden defun
+
 
 @node Binding
 @section Binding
@@ -2796,7 +2867,9 @@ If all @var{vals} evaluate to true, bind them to their 
corresponding
 @var{vars} and execute body. @var{vars-vals} should be a list of (@var{var} 
@var{val})
 pairs.
 
-Note: binding is done according to @code{-let*} (@pxref{-let*}).
+Note: binding is done according to @code{-let*} (@pxref{-let*}).  @var{vals} 
are evaluated
+sequentially, and evaluation stops after the first nil @var{val} is
+encountered.
 
 @example
 @group
@@ -2835,7 +2908,9 @@ If all @var{vals} evaluate to true, bind them to their 
corresponding
 @var{vars} and do @var{then}, otherwise do @var{else}. @var{vars-vals} should 
be a list
 of (@var{var} @var{val}) pairs.
 
-Note: binding is done according to @code{-let*} (@pxref{-let*}).
+Note: binding is done according to @code{-let*} (@pxref{-let*}).  @var{vals} 
are evaluated
+sequentially, and evaluation stops after the first nil @var{val} is
+encountered.
 
 @example
 @group
@@ -2915,10 +2990,10 @@ Vectors:
                      If the @var{pattern} is longer than @var{source}, an 
@code{error} is
                      thrown.
 
-    [a1 a2 a3 ... &rest rest] ) - as above, but bind the rest of
-                                  the sequence to @var{rest}.  This is
-                                  conceptually the same as improper list
-                                  matching (a1 a2 ... aN . rest)
+    [a1 a2 a3 ... &rest rest] - as above, but bind the rest of
+                                the sequence to @var{rest}.  This is
+                                conceptually the same as improper list
+                                matching (a1 a2 ... aN . rest)
 
 Key/value stores: