[elpa] externals/dash 3726eb1 254/316: Improve the examples of -some

[ELPA Syncer]

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

    Improve the examples of -some
    
    * dash.el (--some): Simplify slightly.  Improve docstring.
    (-some): Extend docstring.
    * dev/examples.el (-some): Extend tests.
    
    * README.md:
    * dash.texi: Regenerate docs.
---
 README.md       | 10 +++++-----
 dash.el         | 13 ++++++++-----
 dash.texi       | 14 +++++++-------
 dev/examples.el | 19 +++++++++++++++----
 4 files changed, 35 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index d019838..8979cb3 100644
--- a/README.md
+++ b/README.md
@@ -1979,13 +1979,13 @@ This function's anaphoric counterpart is `--first`.
 #### -some `(pred list)`
 
 Return (`pred` x) for the first `list` item where (`pred` x) is non-nil, else 
nil.
-
-Alias: `-any`
+Alias: `-any`.
+This function's anaphoric counterpart is `--some`.
 
 ```el
-(-some 'even? '(1 2 3)) ;; => t
-(-some 'null '(1 2 3)) ;; => nil
-(-some 'null '(1 2 nil)) ;; => t
+(-some (lambda (s) (string-match-p "x" s)) '("foo" "axe" "xor")) ;; => 1
+(-some (lambda (s) (string-match-p "x" s)) '("foo" "bar" "baz")) ;; => nil
+(--some (member 'foo it) '((foo bar) (baz))) ;; => '(foo bar)
 ```
 
 #### -last `(pred list)`
diff --git a/dash.el b/dash.el
index c8b652b..511222e 100644
--- a/dash.el
+++ b/dash.el
@@ -765,18 +765,21 @@ This function's anaphoric counterpart is `--first'."
 (defalias '--find '--first)
 
 (defmacro --some (form list)
-  "Anaphoric form of `-some'."
+  "Return non-nil if FORM evals to non-nil for at least one item in LIST.
+If so, return the first such result of FORM.
+Each element of LIST in turn is bound to `it' and its index
+within LIST to `it-index' before evaluating FORM.
+This is the anaphoric counterpart to `-some'."
   (declare (debug (form form)))
   (let ((n (make-symbol "needle")))
     `(let (,n)
-       (--each-while ,list (not ,n)
-         (setq ,n ,form))
+       (--each-while ,list (not (setq ,n ,form)))
        ,n)))
 
 (defun -some (pred list)
   "Return (PRED x) for the first LIST item where (PRED x) is non-nil, else nil.
-
-Alias: `-any'"
+Alias: `-any'.
+This function's anaphoric counterpart is `--some'."
   (--some (funcall pred it) list))
 
 (defalias '-any '-some)
diff --git a/dash.texi b/dash.texi
index e998024..f69b59f 100644
--- a/dash.texi
+++ b/dash.texi
@@ -2998,21 +2998,21 @@ This function's anaphoric counterpart is @code{--first}.
 @anchor{-some}
 @defun -some (pred list)
 Return (@var{pred} x) for the first @var{list} item where (@var{pred} x) is 
non-nil, else nil.
-
-Alias: @code{-any}
+Alias: @code{-any}.
+This function's anaphoric counterpart is @code{--some}.
 
 @example
 @group
-(-some 'even? '(1 2 3))
-    @result{} t
+(-some (lambda (s) (string-match-p "x" s)) '("foo" "axe" "xor"))
+    @result{} 1
 @end group
 @group
-(-some 'null '(1 2 3))
+(-some (lambda (s) (string-match-p "x" s)) '("foo" "bar" "baz"))
     @result{} nil
 @end group
 @group
-(-some 'null '(1 2 nil))
-    @result{} t
+(--some (member 'foo it) '((foo bar) (baz)))
+    @result{} '(foo bar)
 @end group
 @end example
 @end defun
diff --git a/dev/examples.el b/dev/examples.el
index 18e5668..a18b9a8 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1006,11 +1006,22 @@ value rather than consuming a list to produce a single 
value."
     (-first #'identity '()) => nil)
 
   (defexamples -some
-    (-some 'even? '(1 2 3)) => t
-    (-some 'null '(1 2 3)) => nil
-    (-some 'null '(1 2 ())) => t
+    (-some (lambda (s) (string-match-p "x" s)) '("foo" "axe" "xor")) => 1
+    (-some (lambda (s) (string-match-p "x" s)) '("foo" "bar" "baz")) => nil
     (--some (member 'foo it) '((foo bar) (baz))) => '(foo bar)
-    (--some (plist-get it :bar) '((:foo 1 :bar 2) (:baz 3))) => 2)
+    (--some (plist-get it :bar) '((:foo 1 :bar 2) (:baz 3))) => 2
+    (-some #'null '(1 2 3)) => nil
+    (-some #'null '(1)) => nil
+    (-some #'null '()) => nil
+    (--some (not it) '(1 2 3)) => nil
+    (--some (not it) '(1)) => nil
+    (--some (not it) '()) => nil
+    (-some #'identity '(1 2 3)) => 1
+    (-some #'identity '(1)) => 1
+    (-some #'identity '()) => nil
+    (--some it '(1 2 3)) => 1
+    (--some it '(1)) => 1
+    (--some it '()) => nil)
 
   (defexamples -last
     (-last 'even? '(1 2 3 4 5 6 3 3 3)) => 6