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

@@ -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 (lambda (s) (string-match-p "x" s)) '("foo" "axe" "xor")) ;; => 1
-(-some 'null '(1 2 3)) ;; => nil
+(-some (lambda (s) (string-match-p "x" s)) '("foo" "bar" "baz")) ;; => nil
-(-some 'null '(1 2 nil)) ;; => t
+(--some (member 'foo it) '((foo bar) (baz))) ;; => '(foo bar)
 ```
 
 #### -last `(pred list)`

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)
+       (--each-while ,list (not (setq ,n ,form)))
-         (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)

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))
+(-some (lambda (s) (string-match-p "x" s)) '("foo" "axe" "xor"))
-    @result{} t
+    @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))
+(--some (member 'foo it) '((foo bar) (baz)))
-    @result{} t
+    @result{} '(foo bar)
 @end group
 @end example
 @end defun

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 (lambda (s) (string-match-p "x" s)) '("foo" "axe" "xor")) => 1
-    (-some 'null '(1 2 3)) => nil
+    (-some (lambda (s) (string-match-p "x" s)) '("foo" "bar" "baz")) => nil
-    (-some 'null '(1 2 ())) => t
     (--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