Mark functions with important-return-value

* dash.el: Include important-return-value in
defun-declarations-alist as needed to pacify warnings in Emacs < 30.

(-map, -reduce-from, -reduce, -reduce-r-from, -reduce-r)
(-reductions-from, -reductions, -reductions-r-from, -reductions-r)
(-filter, -remove, -remove-first, -remove-last, -keep, -map-indexed)
(-map-when, -map-first, -map-last, -mapcat, -iterate, -splice)
(-splice-list, -first, -some, -every, -last, -count, -any?, -all?)
(-none?, -only-some?, -take-while, -drop-while, -update-at)
(-split-with, -split-when, -separate, -partition-by)
(-partition-by-header, -partition-after-pred)
(-partition-before-pred, -group-by, -zip-with, -annotate, -table)
(-table-flat, -find-index, -find-indices, -find-last-index)
(-grade-up, -grade-down, -distinct, -union, -intersection)
(-difference, -frequencies, -permutations, -contains?, -same-items?)
(-sort, -max-by, -min-by, -fix, -unfold, -tree-mapreduce-from)
(-tree-mapreduce, -tree-map, -tree-reduce-from, -tree-reduce)
(-tree-seq, -fixfn): Mark as having important-return-value.

(-snoc, -partition-after-item, -partition-before-item, -powerset)
(-inits, -tails, -common-suffix, -iteratefn, -counter): Declare pure
and side-effect-free.

* dev/examples.el (-every, -sort): Pacify unused value warnings.

* README.md:
* dash.texi: Regenerate docs.

README.md

@@ -1173,7 +1173,7 @@ Return all prefixes of `list`.
 
 #### -tails `(list)`
 
-Return all suffixes of `list`
+Return all suffixes of `list`.
 
 ```el
 (-tails '(1 2 3 4)) ;; => ((1 2 3 4) (2 3 4) (3 4) (4) nil)
@@ -2312,8 +2312,8 @@ Return the sorted list.  `list` is `not` modified by side effects.
 if the first element should sort before the second.
 
 ```el
-(-sort '< '(3 1 2)) ;; => (1 2 3)
+(-sort #'< '(3 1 2)) ;; => (1 2 3)
-(-sort '> '(3 1 2)) ;; => (3 2 1)
+(-sort #'> '(3 1 2)) ;; => (3 2 1)
 (--sort (< it other) '(3 1 2)) ;; => (1 2 3)
 ```
 

dash.el

@@ -35,13 +35,13 @@
   (unless (fboundp 'gv-define-setter)
     (require 'cl))
 
-  ;; TODO: Emacs versions 24.3..24.5 complain about unknown `declare'
+  ;; - 24.3 started complaining about unknown `declare' props.
-  ;; props, so remove this when support for those versions is dropped.
+  ;; - 25 introduced `pure' and `side-effect-free'.
-  (and (< emacs-major-version 25)
+  ;; - 30 introduced `important-return-value'.
-       (boundp 'defun-declarations-alist)
+  (when (boundp 'defun-declarations-alist)
-       (dolist (prop '(pure side-effect-free))
+    (dolist (prop '(important-return-value pure side-effect-free))
-         (unless (assq prop defun-declarations-alist)
+      (unless (assq prop defun-declarations-alist)
-           (push (list prop #'ignore) defun-declarations-alist)))))
+        (push (list prop #'ignore) defun-declarations-alist)))))
 
 (defgroup dash ()
   "Customize group for Dash, a modern list library."
@@ -223,6 +223,7 @@ This function's anaphoric counterpart is `--dotimes'."
   "Apply FN to each item in LIST and return the list of results.
 
 This function's anaphoric counterpart is `--map'."
+  (declare (important-return-value t))
   (mapcar fn list))
 
 (defmacro --map (form list)
@@ -258,6 +259,7 @@ etc.  If LIST is empty, return INIT without calling FN.
 This function's anaphoric counterpart is `--reduce-from'.
 
 For other folds, see also `-reduce' and `-reduce-r'."
+  (declare (important-return-value t))
   (--reduce-from (funcall fn acc it) init list))
 
 (defmacro --reduce (form list)
@@ -289,6 +291,7 @@ arguments.
 This function's anaphoric counterpart is `--reduce'.
 
 For other folds, see also `-reduce-from' and `-reduce-r'."
+  (declare (important-return-value t))
   (if list
       (-reduce-from fn (car list) (cdr list))
     (funcall fn)))
@@ -320,6 +323,7 @@ its last link with INIT, and evaluating the resulting expression.
 This function's anaphoric counterpart is `--reduce-r-from'.
 
 For other folds, see also `-reduce-r' and `-reduce'."
+  (declare (important-return-value t))
   (--reduce-r-from (funcall fn it acc) init list))
 
 (defmacro --reduce-r (form list)
@@ -349,6 +353,7 @@ ignoring its last link, and evaluating the resulting expression.
 This function's anaphoric counterpart is `--reduce-r'.
 
 For other folds, see also `-reduce-r-from' and `-reduce'."
+  (declare (important-return-value t))
   (if list
       (--reduce-r (funcall fn it acc) list)
     (funcall fn)))
@@ -374,6 +379,7 @@ arguments.
 This function's anaphoric counterpart is `--reductions-from'.
 
 For other folds, see also `-reductions' and `-reductions-r'."
+  (declare (important-return-value t))
   (--reductions-from (funcall fn acc it) init list))
 
 (defmacro --reductions (form list)
@@ -400,6 +406,7 @@ when `-reduce' (which see) is called with the same arguments.
 This function's anaphoric counterpart is `--reductions'.
 
 For other folds, see also `-reductions' and `-reductions-r'."
+  (declare (important-return-value t))
   (if list
       (--reductions-from (funcall fn acc it) (car list) (cdr list))
     (list (funcall fn))))
@@ -424,6 +431,7 @@ arguments.
 This function's anaphoric counterpart is `--reductions-r-from'.
 
 For other folds, see also `-reductions' and `-reductions-r'."
+  (declare (important-return-value t))
   (--reductions-r-from (funcall fn it acc) init list))
 
 (defmacro --reductions-r (form list)
@@ -453,6 +461,7 @@ This function's anaphoric counterpart is `--reductions-r'.
 
 For other folds, see also `-reductions-r-from' and
 `-reductions'."
+  (declare (important-return-value t))
   (if list
       (--reductions-r (funcall fn it acc) list)
     (list (funcall fn))))
@@ -477,6 +486,7 @@ Alias: `-select'.
 This function's anaphoric counterpart is `--filter'.
 
 For similar operations, see also `-keep' and `-remove'."
+  (declare (important-return-value t))
   (--filter (funcall pred it) list))
 
 (defalias '-select '-filter)
@@ -499,6 +509,7 @@ Alias: `-reject'.
 This function's anaphoric counterpart is `--remove'.
 
 For similar operations, see also `-keep' and `-filter'."
+  (declare (important-return-value t))
   (--remove (funcall pred it) list))
 
 (defalias '-reject '-remove)
@@ -534,6 +545,7 @@ Alias: `-reject-first'.
 This function's anaphoric counterpart is `--remove-first'.
 
 See also `-map-first', `-remove-item', and `-remove-last'."
+  (declare (important-return-value t))
   (--remove-first (funcall pred it) list))
 
 ;; TODO: #'-quoting the macro upsets Emacs 24.
@@ -559,6 +571,7 @@ Alias: `-reject-last'.
 This function's anaphoric counterpart is `--remove-last'.
 
 See also `-map-last', `-remove-item', and `-remove-first'."
+  (declare (important-return-value t))
   (--remove-last (funcall pred it) list))
 
 (defalias '-reject-last '-remove-last)
@@ -589,6 +602,7 @@ Like `-filter', but returns the non-nil results of FN instead of
 the corresponding elements of LIST.
 
 Its anaphoric counterpart is `--keep'."
+  (declare (important-return-value t))
   (--keep (funcall fn it) list))
 
 (defun -non-nil (list)
@@ -618,6 +632,7 @@ current element within LIST, and the element itself.
 This function's anaphoric counterpart is `--map-indexed'.
 
 For a side-effecting variant, see also `-each-indexed'."
+  (declare (important-return-value t))
   (--map-indexed (funcall fn it-index it) list))
 
 (defmacro --map-when (pred rep list)
@@ -636,6 +651,7 @@ are unchanged, and the rest are mapped through the REP function.
 Alias: `-replace-where'
 
 See also: `-update-at'"
+  (declare (important-return-value t))
   (--map-when (funcall pred it) (funcall rep it) list))
 
 (defalias '-replace-where '-map-when)
@@ -647,6 +663,7 @@ Return a copy of LIST where the first item for which PRED returns
 non-nil is replaced with the result of calling REP on that item.
 
 See also: `-map-when', `-replace-first'"
+  (declare (important-return-value t))
   (let (front)
     (while (and list (not (funcall pred (car list))))
       (push (car list) front)
@@ -668,6 +685,7 @@ Return a copy of LIST where the last item for which PRED returns
 non-nil is replaced with the result of calling REP on that item.
 
 See also: `-map-when', `-replace-last'"
+  (declare (important-return-value t))
   (nreverse (-map-first pred rep (reverse list))))
 
 (defmacro --map-last (pred rep list)
@@ -712,6 +730,7 @@ See also: `-map-last'"
 (defun -mapcat (fn list)
   "Return the concatenation of the result of mapping FN over LIST.
 Thus function FN should return a list."
+  (declare (important-return-value t))
   (--mapcat (funcall fn it) list))
 
 (defmacro --iterate (form init n)
@@ -735,6 +754,7 @@ This means a list of the form:
   (INIT (FUN INIT) (FUN (FUN INIT)) ...)
 
 N is the length of the returned list."
+  (declare (important-return-value t))
   (--iterate (funcall fun it) init n))
 
 (defun -flatten (l)
@@ -816,12 +836,14 @@ marked positions (for example with keywords).
 This function's anaphoric counterpart is `--splice'.
 
 See also: `-splice-list', `-insert-at'."
+  (declare (important-return-value t))
   (--splice (funcall pred it) (funcall fun it) list))
 
 (defun -splice-list (pred new-list list)
   "Splice NEW-LIST in place of elements matching PRED in LIST.
 
 See also: `-splice', `-insert-at'"
+  (declare (important-return-value t))
   (-splice pred (lambda (_) new-list) list))
 
 (defmacro --splice-list (pred new-list list)
@@ -849,6 +871,7 @@ is a dotted list.  With no ARGS, return nil."
 This is like `cons', but operates on the end of list.
 
 If any ELEMENTS are given, append them to the list as well."
+  (declare (pure t) (side-effect-free t))
   (-concat list (list elem) elements))
 
 (defmacro --first (form list)
@@ -874,6 +897,7 @@ use `-first-item'.
 Alias: `-find'.
 
 This function's anaphoric counterpart is `--first'."
+  (declare (important-return-value t))
   (--first (funcall pred it) list))
 
 (defalias '-find #'-first)
@@ -897,6 +921,7 @@ This is the anaphoric counterpart to `-some'."
 Alias: `-any'.
 
 This function's anaphoric counterpart is `--some'."
+  (declare (important-return-value t))
   (--some (funcall pred it) list))
 
 (defalias '-any '-some)
@@ -930,6 +955,7 @@ This function is like `-every-p', but on success returns the last
 non-nil result of PRED instead of just t.
 
 This function's anaphoric counterpart is `--every'."
+  (declare (important-return-value t))
   (--every (funcall pred it) list))
 
 (defmacro --last (form list)
@@ -943,6 +969,7 @@ This function's anaphoric counterpart is `--every'."
 
 (defun -last (pred list)
   "Return the last x in LIST where (PRED x) is non-nil, else nil."
+  (declare (important-return-value t))
   (--last (funcall pred it) list))
 
 (defalias '-first-item #'car
@@ -1033,6 +1060,7 @@ See also: `-first-item', etc."
 
 (defun -count (pred list)
   "Counts the number of items in LIST where (PRED item) is non-nil."
+  (declare (important-return-value t))
   (--count (funcall pred it) list))
 
 (defun ---truthy? (obj)
@@ -1049,6 +1077,7 @@ See also: `-first-item', etc."
   "Return t if (PRED X) is non-nil for any X in LIST, else nil.
 
 Alias: `-any-p', `-some?', `-some-p'"
+  (declare (important-return-value t))
   (--any? (funcall pred it) list))
 
 (defalias '-some? '-any?)
@@ -1087,6 +1116,7 @@ success.
 Alias: `-all-p', `-every-p', `-every?'.
 
 This function's anaphoric counterpart is `--all?'."
+  (declare (important-return-value t))
   (--all? (funcall pred it) list))
 
 (defalias '-every? '-all?)
@@ -1105,6 +1135,7 @@ This function's anaphoric counterpart is `--all?'."
   "Return t if (PRED X) is nil for all X in LIST, else nil.
 
 Alias: `-none-p'"
+  (declare (important-return-value t))
   (--none? (funcall pred it) list))
 
 (defalias '-none-p '-none?)
@@ -1127,6 +1158,7 @@ non-nil for at least one other item in LIST.  Return nil if all
 items satisfy the predicate or none of them do.
 
 Alias: `-only-some-p'"
+  (declare (important-return-value t))
   (--only-some? (funcall pred it) list))
 
 (defalias '-only-some-p '-only-some?)
@@ -1181,6 +1213,7 @@ non-nil.
 This function's anaphoric counterpart is `--take-while'.
 
 For another variant, see also `-drop-while'."
+  (declare (important-return-value t))
   (--take-while (funcall pred it) list))
 
 (defmacro --drop-while (form list)
@@ -1205,6 +1238,7 @@ nil.
 This function's anaphoric counterpart is `--drop-while'.
 
 For another variant, see also `-take-while'."
+  (declare (important-return-value t))
   (--drop-while (funcall pred it) list))
 
 (defun -take (n list)
@@ -1288,6 +1322,7 @@ Return a copy of LIST where the Nth element is replaced with the
 result of calling FUNC on it.
 
 See also: `-map-when'"
+  (declare (important-return-value t))
   (let ((split-list (-split-at n list)))
     (nconc (car split-list)
            (cons (funcall func (car (cadr split-list)))
@@ -1361,6 +1396,7 @@ that do not.  The result is like performing
   ((-take-while PRED LIST) (-drop-while PRED LIST))
 
 but in no more than a single pass through LIST."
+  (declare (important-return-value t))
   (--split-with (funcall pred it) list))
 
 (defmacro -split-on (item list)
@@ -1388,6 +1424,7 @@ the results.  Empty lists are also removed from the result.
 
 This function can be thought of as a generalization of
 `split-string'."
+  (declare (important-return-value t))
   (let (r s)
     (while list
       (if (not (funcall fn (car list)))
@@ -1414,6 +1451,7 @@ The result is like performing
   ((-filter PRED LIST) (-remove PRED LIST))
 
 but in a single pass through LIST."
+  (declare (important-return-value t))
   (--separate (funcall pred it) list))
 
 (defun dash--partition-all-in-steps-reversed (n step list)
@@ -1486,6 +1524,7 @@ those items are discarded."
 
 (defun -partition-by (fn list)
   "Apply FN to each item in LIST, splitting it each time FN returns a new value."
+  (declare (important-return-value t))
   (--partition-by (funcall fn it) list))
 
 (defmacro --partition-by-header (form list)
@@ -1524,6 +1563,7 @@ those items are discarded."
 value. Apply FN to each item in LIST, splitting it each time FN
 returns the header value, but only after seeing at least one
 other value (the body)."
+  (declare (important-return-value t))
   (--partition-by-header (funcall fn it) list))
 
 (defmacro --partition-after-pred (form list)
@@ -1550,20 +1590,24 @@ This is the anaphoric counterpart to `-partition-after-pred'."
   "Partition LIST after each element for which PRED returns non-nil.
 
 This function's anaphoric counterpart is `--partition-after-pred'."
+  (declare (important-return-value t))
   (--partition-after-pred (funcall pred it) list))
 
 (defun -partition-before-pred (pred list)
   "Partition directly before each time PRED is true on an element of LIST."
+  (declare (important-return-value t))
   (nreverse (-map #'reverse
                   (-partition-after-pred pred (reverse list)))))
 
 (defun -partition-after-item (item list)
   "Partition directly after each time ITEM appears in LIST."
+  (declare (pure t) (side-effect-free t))
   (-partition-after-pred (lambda (ele) (equal ele item))
                          list))
 
 (defun -partition-before-item (item list)
   "Partition directly before each time ITEM appears in LIST."
+  (declare (pure t) (side-effect-free t))
   (-partition-before-pred (lambda (ele) (equal ele item))
                           list))
 
@@ -1592,6 +1636,7 @@ This function's anaphoric counterpart is `--partition-after-pred'."
 (defun -group-by (fn list)
   "Separate LIST into an alist whose keys are FN applied to the
 elements of LIST.  Keys are compared by `equal'."
+  (declare (important-return-value t))
   (--group-by (funcall fn it) list))
 
 (defun -interpose (sep list)
@@ -1647,6 +1692,7 @@ shorter list.
 This function's anaphoric counterpart is `--zip-with'.
 
 For other zips, see also `-zip-lists' and `-zip-fill'."
+  (declare (important-return-value t))
   (--zip-with (funcall fn it other) list1 list2))
 
 (defun -zip-lists (&rest lists)
@@ -1844,6 +1890,7 @@ corresponding element of LIST, and RESULT is the value obtained
 by calling FN on ITEM.
 
 This function's anaphoric counterpart is `--annotate'."
+  (declare (important-return-value t))
   (--annotate (funcall fn it) list))
 
 (defun dash--table-carry (lists restore-lists &optional re)
@@ -1872,6 +1919,7 @@ combinations created by taking one element from each list in
 order.  The dimension of the result is (length lists).
 
 See also: `-table-flat'"
+  (declare (important-return-value t))
   (let ((restore-lists (copy-sequence lists))
         (last-list (last lists))
         (re (make-list (length lists) nil)))
@@ -1898,6 +1946,7 @@ of the result.  This is equivalent to calling:
 but the implementation here is much more efficient.
 
 See also: `-flatten-n', `-table'"
+  (declare (important-return-value t))
   (let ((restore-lists (copy-sequence lists))
         (last-list (last lists))
         re)
@@ -1927,6 +1976,7 @@ it returns non-nil, at which point the search terminates.
 This function's anaphoric counterpart is `--find-index'.
 
 See also: `-first', `-find-last-index'."
+  (declare (important-return-value t))
   (--find-index (funcall pred it) list))
 
 (defun -elem-index (elem list)
@@ -1957,6 +2007,7 @@ the same order as they appear in LIST.
 This function's anaphoric counterpart is `--find-indices'.
 
 See also: `-find-index', `-elem-indices'."
+  (declare (important-return-value t))
   (--find-indices (funcall pred it) list))
 
 (defun -elem-indices (elem list)
@@ -1989,6 +2040,7 @@ current list element.
 This function's anaphoric counterpart is `--find-last-index'.
 
 See also: `-last', `-find-index'."
+  (declare (important-return-value t))
   (--find-last-index (funcall pred it) list))
 
 (defun -select-by-indices (indices list)
@@ -2134,6 +2186,7 @@ Note: `it' need not be used in each form."
   "Grade elements of LIST using COMPARATOR relation.
 This yields a permutation vector such that applying this
 permutation to LIST sorts it in ascending order."
+  (declare (important-return-value t))
   (->> (--map-indexed (cons it it-index) list)
        (-sort (lambda (it other) (funcall comparator (car it) (car other))))
        (mapcar #'cdr)))
@@ -2142,6 +2195,7 @@ permutation to LIST sorts it in ascending order."
   "Grade elements of LIST using COMPARATOR relation.
 This yields a permutation vector such that applying this
 permutation to LIST sorts it in descending order."
+  (declare (important-return-value t))
   (->> (--map-indexed (cons it it-index) list)
        (-sort (lambda (it other) (funcall comparator (car other) (car it))))
        (mapcar #'cdr)))
@@ -2881,6 +2935,7 @@ The test for equality is done with `equal', or with `-compare-fn'
 if that is non-nil.
 
 Alias: `-uniq'."
+  (declare (important-return-value t))
   (let (test len)
     (cond ((null list) ())
           ;; Use a hash table if `-compare-fn' is a known hash table
@@ -2910,6 +2965,7 @@ even in the presence of bignum support."
 
 The test for equality is done with `equal', or with `-compare-fn'
 if that is non-nil."
+  (declare (important-return-value t))
   (let ((lists (list list1 list2)) test len union)
     (cond ((null (or list1 list2)))
           ;; Use a hash table if `-compare-fn' is a known hash table
@@ -2932,6 +2988,7 @@ if that is non-nil."
 
 The test for equality is done with `equal', or with `-compare-fn'
 if that is non-nil."
+  (declare (important-return-value t))
   (let (test len)
     (cond ((null (and list1 list2)) ())
           ;; Use a hash table if `-compare-fn' is a known hash table
@@ -2953,6 +3010,7 @@ if that is non-nil."
 
 The test for equality is done with `equal', or with `-compare-fn'
 if that is non-nil."
+  (declare (important-return-value t))
   (let (test len1 len2)
     (cond ((null list1) ())
           ((null list2) (-distinct list1))
@@ -2978,6 +3036,7 @@ if that is non-nil."
 
 (defun -powerset (list)
   "Return the power set of LIST."
+  (declare (pure t) (side-effect-free t))
   (if (null list) (list ())
     (let ((last (-powerset (cdr list))))
       (nconc (mapcar (lambda (x) (cons (car list) x)) last)
@@ -2993,6 +3052,7 @@ The test for equality is done with `equal', or with `-compare-fn'
 if that is non-nil.
 
 See also `-count' and `-group-by'."
+  (declare (important-return-value t))
   (let (test len freqs)
     (cond ((null list))
           ((and (setq test (dash--hash-test-fn))
@@ -3112,6 +3172,7 @@ in LIST, as returned by `-frequencies'."
 
 Duplicate elements of LIST are determined by `equal', or by
 `-compare-fn' if that is non-nil."
+  (declare (important-return-value t))
   (cond ((null list) (list ()))
         ;; Optimization: a traversal of `list' is faster than the
         ;; round trip via `dash--uniq-perms' or `dash--multi-perms'.
@@ -3125,6 +3186,7 @@ Duplicate elements of LIST are determined by `equal', or by
 
 (defun -inits (list)
   "Return all prefixes of LIST."
+  (declare (pure t) (side-effect-free t))
   (let ((res (list list)))
     (setq list (reverse list))
     (while list
@@ -3132,8 +3194,9 @@ Duplicate elements of LIST are determined by `equal', or by
     res))
 
 (defun -tails (list)
-  "Return all suffixes of LIST"
+  "Return all suffixes of LIST."
-  (-reductions-r-from 'cons nil list))
+  (declare (pure t) (side-effect-free t))
+  (-reductions-r-from #'cons nil list))
 
 (defun -common-prefix (&rest lists)
   "Return the longest common prefix of LISTS."
@@ -3143,6 +3206,7 @@ Duplicate elements of LIST are determined by `equal', or by
 
 (defun -common-suffix (&rest lists)
   "Return the longest common suffix of LISTS."
+  (declare (pure t) (side-effect-free t))
   (nreverse (apply #'-common-prefix (mapcar #'reverse lists))))
 
 (defun -contains? (list element)
@@ -3153,6 +3217,7 @@ if that is non-nil.  As with `member', the return value is
 actually the tail of LIST whose car is ELEMENT.
 
 Alias: `-contains-p'."
+  (declare (important-return-value t))
   (funcall (dash--member-fn) element list))
 
 (defalias '-contains-p #'-contains?)
@@ -3166,6 +3231,7 @@ elements.  The test for equality is done with `equal', or with
 `-compare-fn' if that is non-nil.
 
 Alias: `-same-items-p'."
+  (declare (important-return-value t))
   (let (test len1 len2)
     (cond ((null (or list1 list2)))
           ((null (and list1 list2)) nil)
@@ -3231,6 +3297,7 @@ Alias: `-is-infix-p'"
 Return the sorted list.  LIST is NOT modified by side effects.
 COMPARATOR is called with two elements of LIST, and should return non-nil
 if the first element should sort before the second."
+  (declare (important-return-value t))
   (sort (copy-sequence list) comparator))
 
 (defmacro --sort (form list)
@@ -3297,6 +3364,7 @@ the greatest element of the list by the comparison function.
 
 See also combinator `-on' which can transform the values before
 comparing them."
+  (declare (important-return-value t))
   (--reduce (if (funcall comparator it acc) it acc) list))
 
 (defun -min-by (comparator list)
@@ -3305,6 +3373,7 @@ the least element of the list by the comparison function.
 
 See also combinator `-on' which can transform the values before
 comparing them."
+  (declare (important-return-value t))
   (--reduce (if (funcall comparator it acc) acc it) list))
 
 (defmacro --max-by (form list)
@@ -3340,6 +3409,7 @@ the APL language."
   "Compute the (least) fixpoint of FN with initial input LIST.
 
 FN is called at least once, results are compared with `equal'."
+  (declare (important-return-value t))
   (let ((re (funcall fn list)))
     (while (not (equal list re))
       (setq list re)
@@ -3361,6 +3431,7 @@ seed value and builds a (potentially infinite!) list.
 FUN should return nil to stop the generating process, or a
 cons (A . B), where A will be prepended to the result and B is
 the new seed."
+  (declare (important-return-value t))
   (let ((last (funcall fun seed)) r)
     (while last
       (push (car last) r)
@@ -3407,6 +3478,7 @@ INIT-VALUE. See `-reduce-r-from'.
 
 This is the same as calling `-tree-reduce-from' after `-tree-map'
 but is twice as fast as it only traverse the structure once."
+  (declare (important-return-value t))
   (cond
    ((null tree) ())
    ((-cons-pair? tree) (funcall fn tree))
@@ -3434,6 +3506,7 @@ INIT-VALUE. See `-reduce-r-from'.
 
 This is the same as calling `-tree-reduce' after `-tree-map'
 but is twice as fast as it only traverse the structure once."
+  (declare (important-return-value t))
   (cond
    ((null tree) ())
    ((-cons-pair? tree) (funcall fn tree))
@@ -3450,6 +3523,7 @@ but is twice as fast as it only traverse the structure once."
 
 (defun -tree-map (fn tree)
   "Apply FN to each element of TREE while preserving the tree structure."
+  (declare (important-return-value t))
   (cond
    ((null tree) ())
    ((-cons-pair? tree) (funcall fn tree))
@@ -3471,6 +3545,7 @@ then on this result and second element from the list etc.
 
 The initial value is ignored on cons pairs as they always contain
 two elements."
+  (declare (important-return-value t))
   (cond
    ((null tree) ())
    ((-cons-pair? tree) tree)
@@ -3494,6 +3569,7 @@ FN is first applied to first element of the list and second
 element, then on this result and third element from the list etc.
 
 See `-reduce-r' for how exactly are lists of zero or one element handled."
+  (declare (important-return-value t))
   (cond
    ((null tree) ())
    ((-cons-pair? tree) tree)
@@ -3534,6 +3610,7 @@ CHILDREN is a function of one argument that returns the children
 of the passed branch node.
 
 Non-branch nodes are simply copied."
+  (declare (important-return-value t))
   (cons tree
         (and (funcall branch tree)
              (-mapcat (lambda (x) (-tree-seq branch children x))
@@ -3741,6 +3818,7 @@ In types: (a -> a) -> Int -> a -> a.
 This function satisfies the following law:
 
   (funcall (-iteratefn fn n) init) = (-last-item (-iterate fn init (1+ n)))."
+  (declare (pure t) (side-effect-free error-free))
   (lambda (x) (--dotimes n (setq x (funcall fn x))) x))
 
 (defun -counter (&optional beg end inc)
@@ -3752,6 +3830,7 @@ defaults to 0, INC defaults to 1, and if END is nil, the counter
 will increment indefinitely.
 
 The closure accepts any number of arguments, which are discarded."
+  (declare (pure t) (side-effect-free error-free))
   (let ((inc (or inc 1))
         (n (or beg 0)))
     (lambda (&rest _)
@@ -3789,6 +3868,7 @@ iteration halted before converging, a cons with car `halted' and
 cdr the final output from HALT-TEST.
 
 In types: (a -> a) -> a -> a."
+  (declare (important-return-value t))
   (let ((eqfn   (or equal-test 'equal))
         (haltfn (or halt-test
                     (-not

dash.texi

@@ -1534,7 +1534,7 @@ Return all prefixes of @var{list}.
 
 @anchor{-tails}
 @defun -tails (list)
-Return all suffixes of @var{list}
+Return all suffixes of @var{list}.
 
 @example
 @group
@@ -3464,11 +3464,11 @@ if the first element should sort before the second.
 
 @example
 @group
-(-sort '< '(3 1 2))
+(-sort #'< '(3 1 2))
     @result{} (1 2 3)
 @end group
 @group
-(-sort '> '(3 1 2))
+(-sort #'> '(3 1 2))
     @result{} (3 2 1)
 @end group
 @group

dev/examples.el

@@ -895,9 +895,9 @@ value rather than consuming a list to produce a single value."
     (--every it-index '()) => t
     (--every it-index '(1)) => 0
     (--every it-index '(1 2)) => 1
-    (let ((r 'r)) (-every (lambda (x) (setq r x)) '()) r) => 'r
+    (let ((r 'r)) (ignore (-every (lambda (x) (setq r x)) '())) r) => 'r
-    (let ((r 'r)) (-every (lambda (x) (setq r x)) '(nil 1)) r) => nil
+    (let ((r 'r)) (ignore (-every (lambda (x) (setq r x)) '(nil 1))) r) => nil
-    (let (r) (-every (lambda (x) (setq r x)) '(0 1)) r) => 1
+    (let (r) (ignore (-every (lambda (x) (setq r x)) '(0 1))) r) => 1
     (let (i) (--every (ignore (setq i it-index)) '()) i) => nil
     (let (i) (--every (ignore (setq i it-index)) '(a)) i) => 0
     (let (i) (--every (ignore (setq i it-index)) '(a b)) i) => 0)
@@ -1916,10 +1916,10 @@ related predicates."
     (-butlast nil) => nil)
 
   (defexamples -sort
-    (-sort '< '(3 1 2)) => '(1 2 3)
+    (-sort #'< '(3 1 2)) => '(1 2 3)
-    (-sort '> '(3 1 2)) => '(3 2 1)
+    (-sort #'> '(3 1 2)) => '(3 2 1)
     (--sort (< it other) '(3 1 2)) => '(1 2 3)
-    (let ((l '(3 1 2))) (-sort '> l) l) => '(3 1 2))
+    (let ((l '(3 1 2))) (ignore (-sort #'> l)) l) => '(3 1 2))
 
   (defexamples -list
     (-list 1) => '(1)