Fix -some--> docstring and Edebug spec

* dash.el (-some-->): Use a valid Edebug spec, not ->.  Fix
docstring.
* dev/examples.el (-some-->): Improve tests.

* README.md:
* dev/examples.el: Regenerate docs.

README.md

@@ -316,7 +316,7 @@ Functions pretending lists are trees.
 * [-as->](#-as--value-variable-rest-forms) `(value variable &rest forms)`
 * [-some->](#-some--x-optional-form-rest-more) `(x &optional form &rest more)`
 * [-some->>](#-some--x-optional-form-rest-more) `(x &optional form &rest more)`
-* [-some-->](#-some---x-rest-forms) `(x &rest forms)`
+* [-some-->](#-some---expr-rest-forms) `(expr &rest forms)`
 * [-doto](#-doto-init-rest-forms) `(init &rest forms)`
 
 ### Binding
@@ -2321,15 +2321,17 @@ and when that result is non-nil, through the next form, etc.
 (-some->> '(2 4 6) (-last 'even?) (+ 100)) ;; => 106
 ```
 
-#### -some--> `(x &rest forms)`
+#### -some--> `(expr &rest forms)`
 
-When expr is non-nil, thread it through the first form (via [`-->`](#---x-rest-forms)),
+Thread `expr` through `forms` via [`-->`](#---x-rest-forms), while the result is non-nil.
-and when that result is non-nil, through the next form, etc.
+When `expr` evaluates to non-nil, thread the result through the
+first of `forms`, and when that result is non-nil, thread it
+through the next form, etc.
 
 ```el
 (-some--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
 (-some--> nil (concat "abc" it "ghi")) ;; => nil
-(-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it)) ;; => nil
+(-some--> '(0 1) (-remove #'natnump it) (append it it) (-map #'1+ it)) ;; => '()
 ```
 
 #### -doto `(init &rest forms)`

dash.el

@@ -1751,14 +1751,15 @@ and when that result is non-nil, through the next form, etc."
                    (->> ,result ,form))
                  ,@more))))
 
-(defmacro -some--> (x &rest forms)
+(defmacro -some--> (expr &rest forms)
-  "When expr is non-nil, thread it through the first form (via `-->'),
+  "Thread EXPR through FORMS via `-->', while the result is non-nil.
-and when that result is non-nil, through the next form, etc."
+When EXPR evaluates to non-nil, thread the result through the
-  (declare (debug ->)
+first of FORMS, and when that result is non-nil, thread it
-           (indent 1))
+through the next form, etc."
-  (if (null forms) x
+  (declare (debug (form &rest &or symbolp consp)) (indent 1))
+  (if (null forms) expr
     (let ((result (make-symbol "result")))
-      `(-some--> (-when-let (,result ,x)
+      `(-some--> (-when-let (,result ,expr)
                    (--> ,result ,(car forms)))
          ,@(cdr forms)))))
 

dash.texi

@@ -3601,9 +3601,11 @@ and when that result is non-nil, through the next form, etc.
 @end defmac
 
 @anchor{-some-->}
-@defmac -some--> (x &rest forms)
+@defmac -some--> (expr &rest forms)
-When expr is non-nil, thread it through the first form (via @code{-->} (@pxref{-->})),
+Thread @var{expr} through @var{forms} via @code{-->} (@pxref{-->}), while the result is non-nil.
-and when that result is non-nil, through the next form, etc.
+When @var{expr} evaluates to non-nil, thread the result through the
+first of @var{forms}, and when that result is non-nil, thread it
+through the next form, etc.
 
 @example
 @group
@@ -3615,8 +3617,8 @@ and when that result is non-nil, through the next form, etc.
     @result{} nil
 @end group
 @group
-(-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it))
+(-some--> '(0 1) (-remove #'natnump it) (append it it) (-map #'1+ it))
-    @result{} nil
+    @result{} '()
 @end group
 @end example
 @end defmac

dev/examples.el

@@ -1283,9 +1283,13 @@ value rather than consuming a list to produce a single value."
   (defexamples -some-->
     (-some--> "def" (concat "abc" it "ghi")) => "abcdefghi"
     (-some--> nil (concat "abc" it "ghi")) => nil
-    (-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it)) => nil
+    (-some--> '(0 1) (-remove #'natnump it) (append it it) (-map #'1+ it))
-    (-some--> '(2 4 6) (-filter 'even? it) (append it it) (-map 'square it)) => '(4 16 36 4 16 36)
+    => '()
-    (-some--> 1 nil) !!> (void-function nil))
+    (-some--> '(0 1) (-filter #'natnump it) (append it it) (-map #'1+ it))
+    => '(1 2 1 2)
+    (-some--> 1 nil) !!> (void-function nil)
+    (-some--> nil) => nil
+    (-some--> t) => t)
 
   (defexamples -doto
     (-doto (list 1 2 3) pop pop) => '(3)