[elpa] externals/dash c6b92ae 324/426: Reorder the examples into more meaningful blocks

[Phillip Lord]

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

    Reorder the examples into more meaningful blocks
    
    Add aliases, add links to similar functions to docs to improve 
discoverability
    Replace 3rd person docstrings with infinitive docstrings.
---
 README.md       |  459 +++++++++++++++++++++++++++++++++++--------------------
 dash.el         |  230 ++++++++++++++++------------
 dev/examples.el |  159 +++++++++++--------
 3 files changed, 517 insertions(+), 331 deletions(-)

diff --git a/README.md b/README.md
index fe383ae..ade7fd3 100644
--- a/README.md
+++ b/README.md
@@ -35,27 +35,46 @@ Include this in your emacs settings to get syntax 
highlighting:
 ## Functions
 
 
-### List to list
+### Maps
+
+
+Functions in this category take a transforming function, which
+is then applied sequentially to each or selected elements of the
+input list.  The results are collected in order and returned as
+new list.
 
 * [-map](#-map-fn-list) `(fn list)`
-* [-filter](#-filter-pred-list) `(pred list)`
-* [-remove](#-remove-pred-list) `(pred list)`
-* [-keep](#-keep-fn-list) `(fn list)`
 * [-map-when](#-map-when-pred-rep-list) `(pred rep list)`
-* [-replace](#-replace-old-new-list) `(old new list)`
 * [-map-indexed](#-map-indexed-fn-list) `(fn list)`
+* [-annotate](#-annotate-fn-list) `(fn list)`
 * [-splice](#-splice-pred-fun-list) `(pred fun list)`
 * [-splice-list](#-splice-list-pred-new-list-list) `(pred new-list list)`
-* [-flatten](#-flatten-l) `(l)`
-* [-flatten-n](#-flatten-n-num-list) `(num list)`
-* [-concat](#-concat-rest-lists) `(&rest lists)`
 * [-mapcat](#-mapcat-fn-list) `(fn list)`
+
+### Sublist selection
+
+
+Functions returning a sublist of the original list.
+
+* [-filter](#-filter-pred-list) `(pred list)`
+* [-remove](#-remove-pred-list) `(pred list)`
 * [-slice](#-slice-list-from-optional-to-step) `(list from &optional to step)`
 * [-take](#-take-n-list) `(n list)`
 * [-drop](#-drop-n-list) `(n list)`
 * [-take-while](#-take-while-pred-list) `(pred list)`
 * [-drop-while](#-drop-while-pred-list) `(pred list)`
-* [-rotate](#-rotate-n-list) `(n list)`
+* [-select-by-indices](#-select-by-indices-indices-list) `(indices list)`
+
+### List to list
+
+
+Bag of various functions which modify input list.
+
+* [-keep](#-keep-fn-list) `(fn list)`
+* [-concat](#-concat-rest-lists) `(&rest lists)`
+* [-flatten](#-flatten-l) `(l)`
+* [-flatten-n](#-flatten-n-num-list) `(num list)`
+* [-replace](#-replace-old-new-list) `(old new list)`
 * [-insert-at](#-insert-at-n-x-list) `(n x list)`
 * [-replace-at](#-replace-at-n-x-list) `(n x list)`
 * [-update-at](#-update-at-n-func-list) `(n func list)`
@@ -64,6 +83,9 @@ Include this in your emacs settings to get syntax 
highlighting:
 
 ### Reductions
 
+
+Functions reducing lists into single value.
+
 * [-reduce-from](#-reduce-from-fn-initial-value-list) `(fn initial-value list)`
 * [-reduce-r-from](#-reduce-r-from-fn-initial-value-list) `(fn initial-value 
list)`
 * [-reduce](#-reduce-fn-list) `(fn list)`
@@ -98,6 +120,9 @@ Operations dual to reductions, building lists from seed 
value rather than consum
 
 ### Partitioning
 
+
+Functions partitioning the input list into a list of lists.
+
 * [-split-at](#-split-at-n-list) `(n list)`
 * [-split-with](#-split-with-pred-list) `(pred list)`
 * [-split-on](#-split-on-item-list) `(item list)`
@@ -113,17 +138,22 @@ Operations dual to reductions, building lists from seed 
value rather than consum
 
 ### Indexing
 
+
+Return indices of elements based on predicates, sort elements by indices etc.
+
 * [-elem-index](#-elem-index-elem-list) `(elem list)`
 * [-elem-indices](#-elem-indices-elem-list) `(elem list)`
 * [-find-index](#-find-index-pred-list) `(pred list)`
 * [-find-last-index](#-find-last-index-pred-list) `(pred list)`
 * [-find-indices](#-find-indices-pred-list) `(pred list)`
-* [-select-by-indices](#-select-by-indices-indices-list) `(indices list)`
 * [-grade-up](#-grade-up-comparator-list) `(comparator list)`
 * [-grade-down](#-grade-down-comparator-list) `(comparator list)`
 
 ### Set operations
 
+
+Operations pretending lists are sets.
+
 * [-union](#-union-list-list2) `(list list2)`
 * [-difference](#-difference-list-list2) `(list list2)`
 * [-intersection](#-intersection-list-list2) `(list list2)`
@@ -131,6 +161,10 @@ Operations dual to reductions, building lists from seed 
value rather than consum
 
 ### Other list operations
 
+
+Other list functions not fit to be classified elsewhere.
+
+* [-rotate](#-rotate-n-list) `(n list)`
 * [-repeat](#-repeat-n-x) `(n x)`
 * [-cons*](#-cons-rest-args) `(&rest args)`
 * [-snoc](#-snoc-list-elem-rest-elements) `(list elem &rest elements)`
@@ -141,7 +175,6 @@ Operations dual to reductions, building lists from seed 
value rather than consum
 * [-zip-fill](#-zip-fill-fill-value-rest-lists) `(fill-value &rest lists)`
 * [-cycle](#-cycle-list) `(list)`
 * [-pad](#-pad-fill-value-rest-lists) `(fill-value &rest lists)`
-* [-annotate](#-annotate-fn-list) `(fn list)`
 * [-table](#-table-fn-rest-lists) `(fn &rest lists)`
 * [-table-flat](#-table-flat-fn-rest-lists) `(fn &rest lists)`
 * [-first](#-first-pred-list) `(pred list)`
@@ -153,6 +186,9 @@ Operations dual to reductions, building lists from seed 
value rather than consum
 
 ### Tree operations
 
+
+Functions pretending lists are trees.
+
 * [-tree-map](#-tree-map-fn-tree) `(fn tree)`
 * [-tree-reduce](#-tree-reduce-fn-tree) `(fn tree)`
 * [-tree-reduce-from](#-tree-reduce-from-fn-init-value-tree) `(fn init-value 
tree)`
@@ -168,6 +204,9 @@ Operations dual to reductions, building lists from seed 
value rather than consum
 
 ### Binding
 
+
+Convenient versions of `let` and `let*` constructs combined with flow control.
+
 * [-when-let](#-when-let-var-val-rest-body) `(var-val &rest body)`
 * [-when-let*](#-when-let-vars-vals-rest-body) `(vars-vals &rest body)`
 * [-if-let](#-if-let-var-val-then-rest-else) `(var-val then &rest else)`
@@ -175,6 +214,9 @@ Operations dual to reductions, building lists from seed 
value rather than consum
 
 ### Side-effects
 
+
+Functions iterating over lists for side-effect only.
+
 * [-each](#-each-list-fn) `(list fn)`
 * [-each-while](#-each-while-list-pred-fn) `(list pred fn)`
 * [-dotimes](#-dotimes-num-fn) `(num fn)`
@@ -230,11 +272,17 @@ of course the original can also be written like
 which demonstrates the usefulness of both versions.
 
 
-## List to list
+## Maps
+
+
+Functions in this category take a transforming function, which
+is then applied sequentially to each or selected elements of the
+input list.  The results are collected in order and returned as
+new list.
 
 #### -map `(fn list)`
 
-Returns a new list consisting of the result of applying `fn` to the items in 
`list`.
+Return a new list consisting of the result of applying `fn` to the items in 
`list`.
 
 ```cl
 (-map (lambda (num) (* num num)) '(1 2 3 4)) ;; => '(1 4 9 16)
@@ -242,73 +290,42 @@ Returns a new list consisting of the result of applying 
`fn` to the items in `li
 (--map (* it it) '(1 2 3 4)) ;; => '(1 4 9 16)
 ```
 
-#### -filter `(pred list)`
-
-Returns a new list of the items in `list` for which `pred` returns a non-nil 
value.
-
-Alias: `-select`
-
-```cl
-(-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(2 4)
-(-filter 'even? '(1 2 3 4)) ;; => '(2 4)
-(--filter (= 0 (% it 2)) '(1 2 3 4)) ;; => '(2 4)
-```
-
-#### -remove `(pred list)`
-
-Returns a new list of the items in `list` for which `pred` returns nil.
-
-Alias: `-reject`
-
-```cl
-(-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(1 3)
-(-remove 'even? '(1 2 3 4)) ;; => '(1 3)
-(--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => '(1 3)
-```
-
-#### -keep `(fn list)`
-
-Returns a new list of the non-nil results of applying `fn` to the items in 
`list`.
-
-```cl
-(-keep 'cdr '((1 2 3) (4 5) (6))) ;; => '((2 3) (5))
-(-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) ;; => '(40 
50 60)
-(--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => '(40 50 60)
-```
-
 #### -map-when `(pred rep list)`
 
-Returns a new list where the elements in `list` that does not match the `pred` 
function
+Return a new list where the elements in `list` that does not match the `pred` 
function
 are unchanged, and where the elements in `list` that do match the `pred` 
function are mapped
 through the `rep` function.
 
+Alias: `-replace-where`
+
+See also: `-update-at`
+
 ```cl
 (-map-when 'even? 'square '(1 2 3 4)) ;; => '(1 4 3 16)
 (--map-when (> it 2) (* it it) '(1 2 3 4)) ;; => '(1 2 9 16)
 (--map-when (= it 2) 17 '(1 2 3 4)) ;; => '(1 17 3 4)
 ```
 
-#### -replace `(old new list)`
+#### -map-indexed `(fn list)`
 
-Replace all `old` items in `list` with `new`.
+Return a new list consisting of the result of (`fn` index item) for each item 
in `list`.
 
-Elements are compared using `equal`.
+In the anaphoric form `--map-indexed`, the index is exposed as `it-index`.
 
 ```cl
-(-replace 1 "1" '(1 2 3 4 3 2 1)) ;; => '("1" 2 3 4 3 2 "1")
-(-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) ;; => 
'("a" "nice" "bar" "sentence" "about" "bar")
-(-replace 1 2 nil) ;; => nil
+(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) ;; => '(1 1 1 1)
+(--map-indexed (- it it-index) '(1 2 3 4)) ;; => '(1 1 1 1)
 ```
 
-#### -map-indexed `(fn list)`
-
-Returns a new list consisting of the result of (`fn` index item) for each item 
in `list`.
+#### -annotate `(fn list)`
 
-In the anaphoric form `--map-indexed`, the index is exposed as `it-index`.
+Return a list of cons cells where each cell is `fn` applied to each
+element of `list` paired with the unmodified element of `list`.
 
 ```cl
-(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) ;; => '(1 1 1 1)
-(--map-indexed (- it it-index) '(1 2 3 4)) ;; => '(1 1 1 1)
+(-annotate '1+ '(1 2 3)) ;; => '((2 . 1) (3 . 2) (4 . 3))
+(-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) ;; => '((5 "h" 
"e" "l" "l" "o") (2 "hello" "world"))
+(--annotate (< 1 it) '(0 1 2 3)) ;; => '((nil . 0) (nil . 1) (t . 2) (t . 3))
 ```
 
 #### -splice `(pred fun list)`
@@ -321,6 +338,8 @@ This function can be used as replacement for `,@` in case 
you
 need to splice several lists at marked positions (for example
 with keywords).
 
+See also: `-splice-list`, `-insert-at`
+
 ```cl
 (-splice 'even? (lambda (x) (list x x)) '(1 2 3 4)) ;; => '(1 2 2 3 4 4)
 (--splice 't (list it it) '(1 2 3 4)) ;; => '(1 1 2 2 3 3 4 4)
@@ -331,52 +350,52 @@ with keywords).
 
 Splice `new-list` in place of elements matching `pred` in `list`.
 
-See also more general version: `-splice`.
+See also: `-splice`, `-insert-at`
 
 ```cl
 (-splice-list 'keywordp '(a b c) '(1 :foo 2)) ;; => '(1 a b c 2)
 (-splice-list 'keywordp nil '(1 :foo 2)) ;; => '(1 2)
 ```
 
-#### -flatten `(l)`
+#### -mapcat `(fn list)`
 
-Takes a nested list `l` and returns its contents as a single, flat list.
+Return the concatenation of the result of mapping `fn` over `list`.
+Thus function `fn` should return a list.
 
 ```cl
-(-flatten '((1))) ;; => '(1)
-(-flatten '((1 (2 3) (((4 (5))))))) ;; => '(1 2 3 4 5)
-(-flatten '(1 2 (3 . 4))) ;; => '(1 2 (3 . 4))
+(-mapcat 'list '(1 2 3)) ;; => '(1 2 3)
+(-mapcat (lambda (item) (list 0 item)) '(1 2 3)) ;; => '(0 1 0 2 0 3)
+(--mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3)
 ```
 
-#### -flatten-n `(num list)`
 
-Flatten `num` levels of a nested `list`.
+## Sublist selection
 
-```cl
-(-flatten-n 1 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 (3 4) ((5 6)))
-(-flatten-n 2 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 (5 6))
-(-flatten-n 3 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 5 6)
-```
 
-#### -concat `(&rest lists)`
+Functions returning a sublist of the original list.
 
-Returns a new list with the concatenation of the elements in the supplied 
`lists`.
+#### -filter `(pred list)`
+
+Return a new list of the items in `list` for which `pred` returns a non-nil 
value.
+
+Alias: `-select`
 
 ```cl
-(-concat '(1)) ;; => '(1)
-(-concat '(1) '(2)) ;; => '(1 2)
-(-concat '(1) '(2 3) '(4)) ;; => '(1 2 3 4)
+(-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(2 4)
+(-filter 'even? '(1 2 3 4)) ;; => '(2 4)
+(--filter (= 0 (% it 2)) '(1 2 3 4)) ;; => '(2 4)
 ```
 
-#### -mapcat `(fn list)`
+#### -remove `(pred list)`
 
-Returns the concatenation of the result of mapping `fn` over `list`.
-Thus function `fn` should return a list.
+Return a new list of the items in `list` for which `pred` returns nil.
+
+Alias: `-reject`
 
 ```cl
-(-mapcat 'list '(1 2 3)) ;; => '(1 2 3)
-(-mapcat (lambda (item) (list 0 item)) '(1 2 3)) ;; => '(0 1 0 2 0 3)
-(--mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3)
+(-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(1 3)
+(-remove 'even? '(1 2 3 4)) ;; => '(1 3)
+(--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => '(1 3)
 ```
 
 #### -slice `(list from &optional to step)`
@@ -397,7 +416,7 @@ section is returned.  Defaults to 1.
 
 #### -take `(n list)`
 
-Returns a new list of the first `n` items in `list`, or all items if there are 
fewer than `n`.
+Return a new list of the first `n` items in `list`, or all items if there are 
fewer than `n`.
 
 ```cl
 (-take 3 '(1 2 3 4 5)) ;; => '(1 2 3)
@@ -406,7 +425,7 @@ Returns a new list of the first `n` items in `list`, or all 
items if there are f
 
 #### -drop `(n list)`
 
-Returns the tail of `list` without the first `n` items.
+Return the tail of `list` without the first `n` items.
 
 ```cl
 (-drop 3 '(1 2 3 4 5)) ;; => '(4 5)
@@ -415,7 +434,7 @@ Returns the tail of `list` without the first `n` items.
 
 #### -take-while `(pred list)`
 
-Returns a new list of successive items from `list` while (`pred` item) returns 
a non-nil value.
+Return a new list of successive items from `list` while (`pred` item) returns 
a non-nil value.
 
 ```cl
 (-take-while 'even? '(1 2 3 4)) ;; => '()
@@ -425,7 +444,7 @@ Returns a new list of successive items from `list` while 
(`pred` item) returns a
 
 #### -drop-while `(pred list)`
 
-Returns the tail of `list` starting from the first item for which (`pred` 
item) returns nil.
+Return the tail of `list` starting from the first item for which (`pred` item) 
returns nil.
 
 ```cl
 (-drop-while 'even? '(1 2 3 4)) ;; => '(1 2 3 4)
@@ -433,19 +452,86 @@ Returns the tail of `list` starting from the first item 
for which (`pred` item)
 (--drop-while (< it 4) '(1 2 3 4 3 2 1)) ;; => '(4 3 2 1)
 ```
 
-#### -rotate `(n list)`
+#### -select-by-indices `(indices list)`
 
-Rotate `list` `n` places to the right.  With `n` negative, rotate to the left.
-The time complexity is `o`(n).
+Return a list whose elements are elements from `list` selected
+as `(nth i list)` for all i from `indices`.
 
 ```cl
-(-rotate 3 '(1 2 3 4 5 6 7)) ;; => '(5 6 7 1 2 3 4)
-(-rotate -3 '(1 2 3 4 5 6 7)) ;; => '(4 5 6 7 1 2 3)
+(-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" "t" 
"o" "r")) ;; => '("c" "o" "l" "o" "r")
+(-select-by-indices '(2 1 0) '("a" "b" "c")) ;; => '("c" "b" "a")
+(-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) ;; => '("f" "a" "r" 
"f" "a" "l" "l" "a")
+```
+
+
+## List to list
+
+
+Bag of various functions which modify input list.
+
+#### -keep `(fn list)`
+
+Return a new list of the non-nil results of applying `fn` to the items in 
`list`.
+
+```cl
+(-keep 'cdr '((1 2 3) (4 5) (6))) ;; => '((2 3) (5))
+(-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) ;; => '(40 
50 60)
+(--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => '(40 50 60)
+```
+
+#### -concat `(&rest lists)`
+
+Return a new list with the concatenation of the elements in the supplied 
`lists`.
+
+```cl
+(-concat '(1)) ;; => '(1)
+(-concat '(1) '(2)) ;; => '(1 2)
+(-concat '(1) '(2 3) '(4)) ;; => '(1 2 3 4)
+```
+
+#### -flatten `(l)`
+
+Take a nested list `l` and return its contents as a single, flat list.
+
+See also: `-flatten-n`
+
+```cl
+(-flatten '((1))) ;; => '(1)
+(-flatten '((1 (2 3) (((4 (5))))))) ;; => '(1 2 3 4 5)
+(-flatten '(1 2 (3 . 4))) ;; => '(1 2 (3 . 4))
+```
+
+#### -flatten-n `(num list)`
+
+Flatten `num` levels of a nested `list`.
+
+See also: `-flatten`
+
+```cl
+(-flatten-n 1 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 (3 4) ((5 6)))
+(-flatten-n 2 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 (5 6))
+(-flatten-n 3 '((1 2) ((3 4) ((5 6))))) ;; => '(1 2 3 4 5 6)
+```
+
+#### -replace `(old new list)`
+
+Replace all `old` items in `list` with `new`.
+
+Elements are compared using `equal`.
+
+See also: `-replace-at`
+
+```cl
+(-replace 1 "1" '(1 2 3 4 3 2 1)) ;; => '("1" 2 3 4 3 2 "1")
+(-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) ;; => 
'("a" "nice" "bar" "sentence" "about" "bar")
+(-replace 1 2 nil) ;; => nil
 ```
 
 #### -insert-at `(n x list)`
 
-Returns a list with `x` inserted into `list` at position `n`.
+Return a list with `x` inserted into `list` at position `n`.
+
+See also: `-splice`, `-splice-list`
 
 ```cl
 (-insert-at 1 'x '(a b c)) ;; => '(a x b c)
@@ -456,6 +542,8 @@ Returns a list with `x` inserted into `list` at position 
`n`.
 
 Return a list with element at Nth position in `list` replaced with `x`.
 
+See also: `-replace`
+
 ```cl
 (-replace-at 0 9 '(0 1 2 3 4 5)) ;; => '(9 1 2 3 4 5)
 (-replace-at 1 9 '(0 1 2 3 4 5)) ;; => '(0 9 2 3 4 5)
@@ -466,6 +554,8 @@ Return a list with element at Nth position in `list` 
replaced with `x`.
 
 Return a list with element at Nth position in `list` replaced with `(func (nth 
n list))`.
 
+See also: `-map-when`
+
 ```cl
 (-update-at 0 (lambda (x) (+ x 9)) '(0 1 2 3 4 5)) ;; => '(9 1 2 3 4 5)
 (-update-at 1 (lambda (x) (+ x 8)) '(0 1 2 3 4 5)) ;; => '(0 9 2 3 4 5)
@@ -476,6 +566,8 @@ Return a list with element at Nth position in `list` 
replaced with `(func (nth n
 
 Return a list with element at Nth position in `list` removed.
 
+See also: `-remove-at-indices`, `-remove`
+
 ```cl
 (-remove-at 0 '("0" "1" "2" "3" "4" "5")) ;; => '("1" "2" "3" "4" "5")
 (-remove-at 1 '("0" "1" "2" "3" "4" "5")) ;; => '("0" "2" "3" "4" "5")
@@ -488,6 +580,8 @@ Return a list whose elements are elements from `list` 
without
 elements selected as `(nth i list)` for all i
 from `indices`.
 
+See also: `-remove-at`, `-remove`
+
 ```cl
 (-remove-at-indices '(0) '("0" "1" "2" "3" "4" "5")) ;; => '("1" "2" "3" "4" 
"5")
 (-remove-at-indices '(0 2 4) '("0" "1" "2" "3" "4" "5")) ;; => '("1" "3" "5")
@@ -497,11 +591,14 @@ from `indices`.
 
 ## Reductions
 
+
+Functions reducing lists into single value.
+
 #### -reduce-from `(fn initial-value list)`
 
-Returns the result of applying `fn` to `initial-value` and the
+Return the result of applying `fn` to `initial-value` and the
 first item in `list`, then applying `fn` to that result and the 2nd
-item, etc. If `list` contains no items, returns `initial-value` and
+item, etc. If `list` contains no items, return `initial-value` and
 `fn` is not called.
 
 In the anaphoric form `--reduce-from`, the accumulated value is
@@ -530,10 +627,10 @@ operation associates from right instead of from left.
 
 #### -reduce `(fn list)`
 
-Returns the result of applying `fn` to the first 2 items in `list`,
+Return the result of applying `fn` to the first 2 items in `list`,
 then applying `fn` to that result and the 3rd item, etc. If `list`
 contains no items, `fn` must accept no arguments as well, and
-reduce returns the result of calling `fn` with no arguments. If
+reduce return the result of calling `fn` with no arguments. If
 `list` has only 1 item, it is returned and `fn` is not called.
 
 In the anaphoric form `--reduce`, the accumulated value is
@@ -549,7 +646,7 @@ exposed as `acc`.
 
 Replace conses with `fn` and evaluate the resulting expression.
 The final nil is ignored. If `list` contains no items, `fn` must
-accept no arguments as well, and reduce returns the result of
+accept no arguments as well, and reduce return the result of
 calling `fn` with no arguments. If `list` has only 1 item, it is
 returned and `fn` is not called.
 
@@ -687,9 +784,9 @@ the new seed.
 
 #### -any? `(pred list)`
 
-Returns t if (`pred` x) is non-nil for any x in `list`, else nil.
+Return t if (`pred` x) is non-nil for any x in `list`, else nil.
 
-Alias: `-some?`
+Alias: `-any-p`, `-some?`, `-some-p`
 
 ```cl
 (-any? 'even? '(1 2 3)) ;; => t
@@ -699,9 +796,9 @@ Alias: `-some?`
 
 #### -all? `(pred list)`
 
-Returns t if (`pred` x) is non-nil for all x in `list`, else nil.
+Return t if (`pred` x) is non-nil for all x in `list`, else nil.
 
-Alias: `-every?`
+Alias: `-all-p`, `-every?`, `-every-p`
 
 ```cl
 (-all? 'even? '(1 2 3)) ;; => nil
@@ -711,7 +808,9 @@ Alias: `-every?`
 
 #### -none? `(pred list)`
 
-Returns t if (`pred` x) is nil for all x in `list`, else nil.
+Return t if (`pred` x) is nil for all x in `list`, else nil.
+
+Alias: `-none-p`
 
 ```cl
 (-none? 'even? '(1 2 3)) ;; => nil
@@ -721,8 +820,10 @@ Returns t if (`pred` x) is nil for all x in `list`, else 
nil.
 
 #### -only-some? `(pred list)`
 
-Returns `t` if there is a mix of items in `list` that matches and does not 
match `pred`.
-Returns `nil` both if all items match the predicate, and if none of the items 
match the predicate.
+Return `t` if at least one item of `list` matches `pred` and at least one item 
of `list` does not match `pred`.
+Return `nil` both if all items match the predicate or if none of the items 
match the predicate.
+
+Alias: `-only-some-p`
 
 ```cl
 (-only-some? 'even? '(1 2 3)) ;; => t
@@ -732,9 +833,12 @@ Returns `nil` both if all items match the predicate, and 
if none of the items ma
 
 #### -contains? `(list element)`
 
-Return whether `list` contains `element`.
-The test for equality is done with `equal`,
-or with `-compare-fn` if that's non-nil.
+Return non-nil if `list` contains `element`.
+
+The test for equality is done with `equal`, or with `-compare-fn`
+if that's non-nil.
+
+Alias: `-contains-p`
 
 ```cl
 (-contains? '(1 2 3) 1) ;; => t
@@ -748,6 +852,8 @@ Return true if `list` and `list2` has the same items.
 
 The order of the elements in the lists does not matter.
 
+Alias: `-same-items-p`
+
 ```cl
 (-same-items? '(1 2 3) '(1 2 3)) ;; => t
 (-same-items? '(1 2 3) '(3 2 1)) ;; => t
@@ -758,6 +864,8 @@ The order of the elements in the lists does not matter.
 
 Return non-nil if `prefix` is prefix of `list`.
 
+Alias: `-is-prefix-p`
+
 ```cl
 (-is-prefix? '(1 2 3) '(1 2 3 4 5)) ;; => t
 (-is-prefix? '(1 2 3 4 5) '(1 2 3)) ;; => nil
@@ -768,6 +876,8 @@ Return non-nil if `prefix` is prefix of `list`.
 
 Return non-nil if `suffix` is suffix of `list`.
 
+Alias: `-is-suffix-p`
+
 ```cl
 (-is-suffix? '(3 4 5) '(1 2 3 4 5)) ;; => t
 (-is-suffix? '(1 2 3 4 5) '(3 4 5)) ;; => nil
@@ -780,6 +890,8 @@ Return non-nil if `infix` is infix of `list`.
 
 This operation runs in `o`(n^2) time
 
+Alias: `-is-infix-p`
+
 ```cl
 (-is-infix? '(1 2 3) '(1 2 3 4 5)) ;; => t
 (-is-infix? '(2 3 4) '(1 2 3 4 5)) ;; => t
@@ -789,9 +901,12 @@ This operation runs in `o`(n^2) time
 
 ## Partitioning
 
+
+Functions partitioning the input list into a list of lists.
+
 #### -split-at `(n list)`
 
-Returns a list of ((-take `n` `list`) (-drop `n` `list`)), in no more than one 
pass through the list.
+Return a list of ((-take `n` `list`) (-drop `n` `list`)), in no more than one 
pass through the list.
 
 ```cl
 (-split-at 3 '(1 2 3 4 5)) ;; => '((1 2 3) (4 5))
@@ -800,7 +915,7 @@ Returns a list of ((-take `n` `list`) (-drop `n` `list`)), 
in no more than one p
 
 #### -split-with `(pred list)`
 
-Returns a list of ((-take-while `pred` `list`) (-drop-while `pred` `list`)), 
in no more than one pass through the list.
+Return a list of ((-take-while `pred` `list`) (-drop-while `pred` `list`)), in 
no more than one pass through the list.
 
 ```cl
 (-split-with 'even? '(1 2 3 4)) ;; => '(nil (1 2 3 4))
@@ -817,7 +932,7 @@ Empty lists are also removed from the result.
 
 Comparison is done by `equal`.
 
-See also `-split-when`.
+See also `-split-when`
 
 ```cl
 (-split-on '| '(Nil | Leaf a | Node [Tree a])) ;; => '((Nil) (Leaf a) (Node 
[Tree a]))
@@ -843,7 +958,7 @@ This function can be thought of as a generalization of
 
 #### -separate `(pred list)`
 
-Returns a list of ((-filter `pred` `list`) (-remove `pred` `list`)), in one 
pass through the list.
+Return a list of ((-filter `pred` `list`) (-remove `pred` `list`)), in one 
pass through the list.
 
 ```cl
 (-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ;; => '((2 4 6) (1 
3 5 7))
@@ -853,7 +968,7 @@ Returns a list of ((-filter `pred` `list`) (-remove `pred` 
`list`)), in one pass
 
 #### -partition `(n list)`
 
-Returns a new list with the items in `list` grouped into `n-`sized sublists.
+Return a new list with the items in `list` grouped into `n-`sized sublists.
 If there are not enough items to make the last group `n-`sized,
 those items are discarded.
 
@@ -865,7 +980,7 @@ those items are discarded.
 
 #### -partition-all `(n list)`
 
-Returns a new list with the items in `list` grouped into `n-`sized sublists.
+Return a new list with the items in `list` grouped into `n-`sized sublists.
 The last group may contain less than `n` items.
 
 ```cl
@@ -876,7 +991,7 @@ The last group may contain less than `n` items.
 
 #### -partition-in-steps `(n step list)`
 
-Returns a new list with the items in `list` grouped into `n-`sized sublists at 
offsets `step` apart.
+Return a new list with the items in `list` grouped into `n-`sized sublists at 
offsets `step` apart.
 If there are not enough items to make the last group `n-`sized,
 those items are discarded.
 
@@ -888,7 +1003,7 @@ those items are discarded.
 
 #### -partition-all-in-steps `(n step list)`
 
-Returns a new list with the items in `list` grouped into `n-`sized sublists at 
offsets `step` apart.
+Return a new list with the items in `list` grouped into `n-`sized sublists at 
offsets `step` apart.
 The last groups may contain less than `n` items.
 
 ```cl
@@ -899,7 +1014,7 @@ The last groups may contain less than `n` items.
 
 #### -partition-by `(fn list)`
 
-Applies `fn` to each item in `list`, splitting it each time `fn` returns a new 
value.
+Apply `fn` to each item in `list`, splitting it each time `fn` returns a new 
value.
 
 ```cl
 (-partition-by 'even? '()) ;; => '()
@@ -909,8 +1024,8 @@ Applies `fn` to each item in `list`, splitting it each 
time `fn` returns a new v
 
 #### -partition-by-header `(fn list)`
 
-Applies `fn` to the first item in `list`. That is the header
-value. Applies `fn` to each item in `list`, splitting it each time `fn`
+Apply `fn` to the first item in `list`. That is the header
+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).
 
@@ -934,6 +1049,9 @@ elements of `list`.  Keys are compared by `equal`.
 
 ## Indexing
 
+
+Return indices of elements based on predicates, sort elements by indices etc.
+
 #### -elem-index `(elem list)`
 
 Return the index of the first element in the given `list` which
@@ -992,20 +1110,9 @@ predicate `pred`, in ascending order.
 (-find-indices (-partial 'string-lessp "baz") '("bar" "foo" "baz")) ;; => '(1)
 ```
 
-#### -select-by-indices `(indices list)`
-
-Return a list whose elements are elements from `list` selected
-as `(nth i list)` for all i from `indices`.
-
-```cl
-(-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" "t" 
"o" "r")) ;; => '("c" "o" "l" "o" "r")
-(-select-by-indices '(2 1 0) '("a" "b" "c")) ;; => '("c" "b" "a")
-(-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) ;; => '("f" "a" "r" 
"f" "a" "l" "l" "a")
-```
-
 #### -grade-up `(comparator list)`
 
-Grades elements of `list` using `comparator` relation, yielding a
+Grade elements of `list` using `comparator` relation, yielding a
 permutation vector such that applying this permutation to `list`
 sorts it in ascending order.
 
@@ -1016,7 +1123,7 @@ sorts it in ascending order.
 
 #### -grade-down `(comparator list)`
 
-Grades elements of `list` using `comparator` relation, yielding a
+Grade elements of `list` using `comparator` relation, yielding a
 permutation vector such that applying this permutation to `list`
 sorts it in descending order.
 
@@ -1028,6 +1135,9 @@ sorts it in descending order.
 
 ## Set operations
 
+
+Operations pretending lists are sets.
+
 #### -union `(list list2)`
 
 Return a new list containing the elements of `list1` and elements of `list2` 
that are not in `list1`.
@@ -1080,10 +1190,23 @@ Alias: `-uniq`
 
 ## Other list operations
 
+
+Other list functions not fit to be classified elsewhere.
+
+#### -rotate `(n list)`
+
+Rotate `list` `n` places to the right.  With `n` negative, rotate to the left.
+The time complexity is `o`(n).
+
+```cl
+(-rotate 3 '(1 2 3 4 5 6 7)) ;; => '(5 6 7 1 2 3 4)
+(-rotate -3 '(1 2 3 4 5 6 7)) ;; => '(4 5 6 7 1 2 3)
+```
+
 #### -repeat `(n x)`
 
 Return a list with `x` repeated `n` times.
-Returns nil if `n` is less than 1.
+Return nil if `n` is less than 1.
 
 ```cl
 (-repeat 3 :a) ;; => '(:a :a :a)
@@ -1093,7 +1216,7 @@ Returns nil if `n` is less than 1.
 
 #### -cons* `(&rest args)`
 
-Makes a new list from the elements of `args`.
+Make a new list from the elements of `args`.
 
 The last 2 members of `args` are used as the final cons of the
 result so if the final member of `args` is not a list the result is
@@ -1121,7 +1244,7 @@ If `elements` is non nil, append these to the list as 
well.
 
 #### -interpose `(sep list)`
 
-Returns a new list of all elements in `list` separated by `sep`.
+Return a new list of all elements in `list` separated by `sep`.
 
 ```cl
 (-interpose "-" '()) ;; => '()
@@ -1131,7 +1254,7 @@ Returns a new list of all elements in `list` separated by 
`sep`.
 
 #### -interleave `(&rest lists)`
 
-Returns a new list of the first item in each list, then the second etc.
+Return a new list of the first item in each list, then the second etc.
 
 ```cl
 (-interleave '(1 2) '("a" "b")) ;; => '(1 "a" 2 "b")
@@ -1182,7 +1305,7 @@ longest input list.
 
 #### -cycle `(list)`
 
-Returns an infinite copy of `list` that will cycle through the
+Return an infinite copy of `list` that will cycle through the
 elements and repeat from the beginning.
 
 ```cl
@@ -1202,17 +1325,6 @@ will all have the same length.
 (-pad 0 '(1 2 3) '(4 5)) ;; => '((1 2 3) (4 5 0))
 ```
 
-#### -annotate `(fn list)`
-
-Returns a list of cons cells where each cell is `fn` applied to each
-element of `list` paired with the unmodified element of `list`.
-
-```cl
-(-annotate '1+ '(1 2 3)) ;; => '((2 . 1) (3 . 2) (4 . 3))
-(-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) ;; => '((5 "h" 
"e" "l" "l" "o") (2 "hello" "world"))
-(--annotate (< 1 it) '(0 1 2 3)) ;; => '((nil . 0) (nil . 1) (t . 2) (t . 3))
-```
-
 #### -table `(fn &rest lists)`
 
 Compute outer product of `lists` using function `fn`.
@@ -1224,7 +1336,7 @@ The outer product is computed by applying fn to all 
possible
 combinations created by taking one element from each list in
 order.  The dimension of the result is (length lists).
 
-See also: `-table-flat`.
+See also: `-table-flat`
 
 ```cl
 (-table '* '(1 2 3) '(1 2 3)) ;; => '((1 2 3) (2 4 6) (3 6 9))
@@ -1248,7 +1360,7 @@ of the result.  This is equivalent to calling:
 
 but the implementation here is much more efficient.
 
-See also: `-flatten-n`, `-table`.
+See also: `-flatten-n`, `-table`
 
 ```cl
 (-table-flat 'list '(1 2 3) '(a b c)) ;; => '((1 a) (2 a) (3 a) (1 b) (2 b) (3 
b) (1 c) (2 c) (3 c))
@@ -1258,11 +1370,11 @@ See also: `-flatten-n`, `-table`.
 
 #### -first `(pred list)`
 
-Returns the first x in `list` where (`pred` x) is non-nil, else nil.
+Return the first x in `list` where (`pred` x) is non-nil, else nil.
 
 To get the first item in the list no questions asked, use `car`.
 
-This function is also available as `-find`.
+Alias: `-find`
 
 ```cl
 (-first 'even? '(1 2 3)) ;; => 2
@@ -1282,7 +1394,7 @@ Return the last x in `list` where (`pred` x) is non-nil, 
else nil.
 
 #### -first-item `(list)`
 
-Returns the first item of `list`, or nil on an empty list.
+Return the first item of `list`, or nil on an empty list.
 
 ```cl
 (-first-item '(1 2 3)) ;; => 1
@@ -1291,7 +1403,7 @@ Returns the first item of `list`, or nil on an empty list.
 
 #### -last-item `(list)`
 
-Returns the last item of `list`, or nil on an empty list.
+Return the last item of `list`, or nil on an empty list.
 
 ```cl
 (-last-item '(1 2 3)) ;; => 3
@@ -1301,7 +1413,7 @@ Returns the last item of `list`, or nil on an empty list.
 #### -sort `(comparator list)`
 
 Sort `list`, stably, comparing elements using `comparator`.
-Returns the sorted list.  `list` is `not` modified by side effects.
+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.
 
@@ -1326,6 +1438,9 @@ not, return a list with `args` as elements.
 
 ## Tree operations
 
+
+Functions pretending lists are trees.
+
 #### -tree-map `(fn tree)`
 
 Apply `fn` to each element of `tree` while preserving the tree structure.
@@ -1420,9 +1535,9 @@ structure such as plist or alist.
 
 #### -> `(x &optional form &rest more)`
 
-Threads the expr through the forms. Inserts `x` as the second
-item in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+Thread the expr through the forms. Insert `x` as the second item
+in the first form, making a list of it if it is not a list
+already. If there are more forms, insert the first form as the
 second item in second form, etc.
 
 ```cl
@@ -1433,9 +1548,9 @@ second item in second form, etc.
 
 #### ->> `(x form &rest more)`
 
-Threads the expr through the forms. Inserts `x` as the last item
+Thread the expr through the forms. Insert `x` as the last item
 in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+already. If there are more forms, insert the first form as the
 last item in second form, etc.
 
 ```cl
@@ -1446,10 +1561,10 @@ last item in second form, etc.
 
 #### --> `(x form &rest more)`
 
-Threads the expr through the forms. Inserts `x` at the position
+Thread the expr through the forms. Insert `x` at the position
 signified by the token `it` in the first form. If there are more
-forms, inserts the first form at the position signified by `it`
-in in second form, etc.
+forms, insert the first form at the position signified by `it` in
+in second form, etc.
 
 ```cl
 (--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
@@ -1460,6 +1575,9 @@ in in second form, etc.
 
 ## Binding
 
+
+Convenient versions of `let` and `let*` constructs combined with flow control.
+
 #### -when-let `(var-val &rest body)`
 
 If `val` evaluates to non-nil, bind it to `var` and execute body.
@@ -1506,9 +1624,12 @@ of (`var` `val`) pairs (corresponding to the bindings of 
`let*`).
 
 ## Side-effects
 
+
+Functions iterating over lists for side-effect only.
+
 #### -each `(list fn)`
 
-Calls `fn` with every item in `list`. Returns nil, used for side-effects only.
+Call `fn` with every item in `list`. Return nil, used for side-effects only.
 
 ```cl
 (let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) ;; => nil
@@ -1518,8 +1639,8 @@ Calls `fn` with every item in `list`. Returns nil, used 
for side-effects only.
 
 #### -each-while `(list pred fn)`
 
-Calls `fn` with every item in `list` while (`pred` item) is non-nil.
-Returns nil, used for side-effects only.
+Call `fn` with every item in `list` while (`pred` item) is non-nil.
+Return nil, used for side-effects only.
 
 ```cl
 (let (s) (-each-while '(2 4 5 6) 'even? (lambda (item) (!cons item s))) s) ;; 
=> '(4 2)
@@ -1540,7 +1661,7 @@ Repeatedly calls `fn` (presumably for side-effects) 
passing in integers from 0 t
 
 #### !cons `(car cdr)`
 
-Destructive: Sets `cdr` to the cons of `car` and `cdr`.
+Destructive: Set `cdr` to the cons of `car` and `cdr`.
 
 ```cl
 (let (l) (!cons 5 l) l) ;; => '(5)
@@ -1549,7 +1670,7 @@ Destructive: Sets `cdr` to the cons of `car` and `cdr`.
 
 #### !cdr `(list)`
 
-Destructive: Sets `list` to the cdr of `list`.
+Destructive: Set `list` to the cdr of `list`.
 
 ```cl
 (let ((l '(3))) (!cdr l) l) ;; => '()
diff --git a/dash.el b/dash.el
index 775e799..d0aae94 100644
--- a/dash.el
+++ b/dash.el
@@ -45,11 +45,11 @@ special values."
   :group 'dash)
 
 (defmacro !cons (car cdr)
-  "Destructive: Sets CDR to the cons of CAR and CDR."
+  "Destructive: Set CDR to the cons of CAR and CDR."
   `(setq ,cdr (cons ,car ,cdr)))
 
 (defmacro !cdr (list)
-  "Destructive: Sets LIST to the cdr of LIST."
+  "Destructive: Set LIST to the cdr of LIST."
   `(setq ,list (cdr ,list)))
 
 (defmacro --each (list &rest body)
@@ -66,7 +66,7 @@ special values."
          (!cdr ,l)))))
 
 (defun -each (list fn)
-  "Calls FN with every item in LIST. Returns nil, used for side-effects only."
+  "Call FN with every item in LIST. Return nil, used for side-effects only."
   (--each list (funcall fn it)))
 
 (put '-each 'lisp-indent-function 1)
@@ -87,8 +87,8 @@ special values."
          (!cdr ,l)))))
 
 (defun -each-while (list pred fn)
-  "Calls FN with every item in LIST while (PRED item) is non-nil.
-Returns nil, used for side-effects only."
+  "Call FN with every item in LIST while (PRED item) is non-nil.
+Return nil, used for side-effects only."
   (--each-while list (funcall pred it) (funcall fn it)))
 
 (put '-each-while 'lisp-indent-function 2)
@@ -111,7 +111,7 @@ Returns nil, used for side-effects only."
 (put '-dotimes 'lisp-indent-function 1)
 
 (defun -map (fn list)
-  "Returns a new list consisting of the result of applying FN to the items in 
LIST."
+  "Return a new list consisting of the result of applying FN to the items in 
LIST."
   (mapcar fn list))
 
 (defmacro --map (form list)
@@ -127,9 +127,9 @@ Returns nil, used for side-effects only."
      acc))
 
 (defun -reduce-from (fn initial-value list)
-  "Returns the result of applying FN to INITIAL-VALUE and the
+  "Return the result of applying FN to INITIAL-VALUE and the
 first item in LIST, then applying FN to that result and the 2nd
-item, etc. If LIST contains no items, returns INITIAL-VALUE and
+item, etc. If LIST contains no items, return INITIAL-VALUE and
 FN is not called.
 
 In the anaphoric form `--reduce-from', the accumulated value is
@@ -146,10 +146,10 @@ exposed as `acc`."
          (let (acc it) ,form)))))
 
 (defun -reduce (fn list)
-  "Returns the result of applying FN to the first 2 items in LIST,
+  "Return the result of applying FN to the first 2 items in LIST,
 then applying FN to that result and the 3rd item, etc. If LIST
 contains no items, FN must accept no arguments as well, and
-reduce returns the result of calling FN with no arguments. If
+reduce return the result of calling FN with no arguments. If
 LIST has only 1 item, it is returned and FN is not called.
 
 In the anaphoric form `--reduce', the accumulated value is
@@ -176,7 +176,7 @@ operation associates from right instead of from left."
 (defun -reduce-r (fn list)
   "Replace conses with FN and evaluate the resulting expression.
 The final nil is ignored. If LIST contains no items, FN must
-accept no arguments as well, and reduce returns the result of
+accept no arguments as well, and reduce return the result of
 calling FN with no arguments. If LIST has only 1 item, it is
 returned and FN is not called.
 
@@ -204,7 +204,7 @@ associates from right instead of from left."
        (nreverse ,r))))
 
 (defun -filter (pred list)
-  "Returns a new list of the items in LIST for which PRED returns a non-nil 
value.
+  "Return a new list of the items in LIST for which PRED returns a non-nil 
value.
 
 Alias: `-select'"
   (--filter (funcall pred it) list))
@@ -218,7 +218,7 @@ Alias: `-select'"
   `(--filter (not ,form) ,list))
 
 (defun -remove (pred list)
-  "Returns a new list of the items in LIST for which PRED returns nil.
+  "Return a new list of the items in LIST for which PRED returns nil.
 
 Alias: `-reject'"
   (--remove (funcall pred it) list))
@@ -236,17 +236,9 @@ Alias: `-reject'"
        (nreverse ,r))))
 
 (defun -keep (fn list)
-  "Returns a new list of the non-nil results of applying FN to the items in 
LIST."
+  "Return a new list of the non-nil results of applying FN to the items in 
LIST."
   (--keep (funcall fn it) list))
 
-(defmacro --map-when (pred rep list)
-  "Anaphoric form of `-map-when'."
-  (declare (debug (form form form)))
-  (let ((r (make-symbol "result")))
-    `(let (,r)
-       (--each ,list (!cons (if ,pred ,rep it) ,r))
-       (nreverse ,r))))
-
 (defmacro --map-indexed (form list)
   "Anaphoric form of `-map-indexed'."
   (declare (debug (form form)))
@@ -257,38 +249,56 @@ Alias: `-reject'"
        (nreverse ,r))))
 
 (defun -map-indexed (fn list)
-  "Returns a new list consisting of the result of (FN index item) for each 
item in LIST.
+  "Return a new list consisting of the result of (FN index item) for each item 
in LIST.
 
 In the anaphoric form `--map-indexed', the index is exposed as `it-index`."
   (--map-indexed (funcall fn it-index it) list))
 
+(defmacro --map-when (pred rep list)
+  "Anaphoric form of `-map-when'."
+  (declare (debug (form form form)))
+  (let ((r (make-symbol "result")))
+    `(let (,r)
+       (--each ,list (!cons (if ,pred ,rep it) ,r))
+       (nreverse ,r))))
+
 (defun -map-when (pred rep list)
-  "Returns a new list where the elements in LIST that does not match the PRED 
function
+  "Return a new list where the elements in LIST that does not match the PRED 
function
 are unchanged, and where the elements in LIST that do match the PRED function 
are mapped
-through the REP function."
+through the REP function.
+
+Alias: `-replace-where'
+
+See also: `-update-at'"
   (--map-when (funcall pred it) (funcall rep it) list))
 
-(defalias '--replace-where '--map-when)
 (defalias '-replace-where '-map-when)
+(defalias '--replace-where '--map-when)
 
 (defun -replace (old new list)
   "Replace all OLD items in LIST with NEW.
 
-Elements are compared using `equal'."
+Elements are compared using `equal'.
+
+See also: `-replace-at'"
   (--map-when (equal it old) new list))
 
 (defun -flatten (l)
-  "Takes a nested list L and returns its contents as a single, flat list."
+  "Take a nested list L and return its contents as a single, flat list.
+
+See also: `-flatten-n'"
   (if (and (listp l) (listp (cdr l)))
       (-mapcat '-flatten l)
     (list l)))
 
 (defun -flatten-n (num list)
-  "Flatten NUM levels of a nested LIST."
+  "Flatten NUM levels of a nested LIST.
+
+See also: `-flatten'"
   (-last-item (--iterate (--mapcat (-list it) it) list (1+ num))))
 
 (defun -concat (&rest lists)
-  "Returns a new list with the concatenation of the elements in the supplied 
LISTS."
+  "Return a new list with the concatenation of the elements in the supplied 
LISTS."
   (apply 'append lists))
 
 (defmacro --mapcat (form list)
@@ -297,7 +307,7 @@ Elements are compared using `equal'."
   `(apply 'append (--map ,form ,list)))
 
 (defun -mapcat (fn list)
-  "Returns the concatenation of the result of mapping FN over LIST.
+  "Return the concatenation of the result of mapping FN over LIST.
 Thus function FN should return a list."
   (--mapcat (funcall fn it) list))
 
@@ -308,7 +318,9 @@ FUN takes the element matching PRED as input.
 
 This function can be used as replacement for `,@' in case you
 need to splice several lists at marked positions (for example
-with keywords)."
+with keywords).
+
+See also: `-splice-list', `-insert-at'"
   (let (r)
     (--each list
       (if (funcall pred it)
@@ -324,7 +336,7 @@ with keywords)."
 (defun -splice-list (pred new-list list)
   "Splice NEW-LIST in place of elements matching PRED in LIST.
 
-See also more general version: `-splice'."
+See also: `-splice', `-insert-at'"
   (-splice pred (lambda (_) new-list) list))
 
 (defun --splice-list (pred new-list list)
@@ -332,7 +344,7 @@ See also more general version: `-splice'."
   `(-splice-list (lambda (it) ,pred) ,new-list ,list))
 
 (defun -cons* (&rest args)
-  "Makes a new list from the elements of ARGS.
+  "Make a new list from the elements of ARGS.
 
 The last 2 members of ARGS are used as the final cons of the
 result so if the final member of ARGS is not a list the result is
@@ -357,11 +369,11 @@ If ELEMENTS is non nil, append these to the list as well."
        ,n)))
 
 (defun -first (pred list)
-  "Returns the first x in LIST where (PRED x) is non-nil, else nil.
+  "Return the first x in LIST where (PRED x) is non-nil, else nil.
 
 To get the first item in the list no questions asked, use `car'.
 
-This function is also available as `-find'."
+Alias: `-find'"
   (--first (funcall pred it) list))
 
 (defalias '-find '-first)
@@ -381,10 +393,10 @@ This function is also available as `-find'."
   (--last (funcall pred it) list))
 
 (defalias '-first-item 'car
-  "Returns the first item of LIST, or nil on an empty list.")
+  "Return the first item of LIST, or nil on an empty list.")
 
 (defun -last-item (list)
-  "Returns the last item of LIST, or nil on an empty list."
+  "Return the last item of LIST, or nil on an empty list."
   (car (last list)))
 
 (defmacro --count (pred list)
@@ -408,14 +420,13 @@ This function is also available as `-find'."
   `(---truthy? (--first ,form ,list)))
 
 (defun -any? (pred list)
-  "Returns t if (PRED x) is non-nil for any x in LIST, else nil.
+  "Return t if (PRED x) is non-nil for any x in LIST, else nil.
 
-Alias: `-some?'"
+Alias: `-any-p', `-some?', `-some-p'"
   (--any? (funcall pred it) list))
 
 (defalias '-some? '-any?)
 (defalias '--some? '--any?)
-
 (defalias '-any-p '-any?)
 (defalias '--any-p '--any?)
 (defalias '-some-p '-any?)
@@ -430,14 +441,13 @@ Alias: `-some?'"
        (---truthy? ,a))))
 
 (defun -all? (pred list)
-  "Returns t if (PRED x) is non-nil for all x in LIST, else nil.
+  "Return t if (PRED x) is non-nil for all x in LIST, else nil.
 
-Alias: `-every?'"
+Alias: `-all-p', `-every?', `-every-p'"
   (--all? (funcall pred it) list))
 
 (defalias '-every? '-all?)
 (defalias '--every? '--all?)
-
 (defalias '-all-p '-all?)
 (defalias '--all-p '--all?)
 (defalias '-every-p '-all?)
@@ -449,7 +459,9 @@ Alias: `-every?'"
   `(--all? (not ,form) ,list))
 
 (defun -none? (pred list)
-  "Returns t if (PRED x) is nil for all x in LIST, else nil."
+  "Return t if (PRED x) is nil for all x in LIST, else nil.
+
+Alias: `-none-p'"
   (--none? (funcall pred it) list))
 
 (defalias '-none-p '-none?)
@@ -466,8 +478,10 @@ Alias: `-every?'"
        (---truthy? (and ,y ,n)))))
 
 (defun -only-some? (pred list)
-  "Returns `t` if there is a mix of items in LIST that matches and does not 
match PRED.
-Returns `nil` both if all items match the predicate, and if none of the items 
match the predicate."
+  "Return `t` if at least one item of LIST matches PRED and at least one item 
of LIST does not match PRED.
+Return `nil` both if all items match the predicate or if none of the items 
match the predicate.
+
+Alias: `-only-some-p'"
   (--only-some? (funcall pred it) list))
 
 (defalias '-only-some-p '-only-some?)
@@ -500,7 +514,7 @@ section is returned.  Defaults to 1."
     (nreverse new-list)))
 
 (defun -take (n list)
-  "Returns a new list of the first N items in LIST, or all items if there are 
fewer than N."
+  "Return a new list of the first N items in LIST, or all items if there are 
fewer than N."
   (let (result)
     (--dotimes n
       (when list
@@ -508,7 +522,7 @@ section is returned.  Defaults to 1."
         (!cdr list)))
     (nreverse result)))
 
-(defalias '-drop 'nthcdr "Returns the tail of LIST without the first N items.")
+(defalias '-drop 'nthcdr "Return the tail of LIST without the first N items.")
 
 (defmacro --take-while (form list)
   "Anaphoric form of `-take-while'."
@@ -519,7 +533,7 @@ section is returned.  Defaults to 1."
        (nreverse ,r))))
 
 (defun -take-while (pred list)
-  "Returns a new list of successive items from LIST while (PRED item) returns 
a non-nil value."
+  "Return a new list of successive items from LIST while (PRED item) returns a 
non-nil value."
   (--take-while (funcall pred it) list))
 
 (defmacro --drop-while (form list)
@@ -532,11 +546,11 @@ section is returned.  Defaults to 1."
        ,l)))
 
 (defun -drop-while (pred list)
-  "Returns the tail of LIST starting from the first item for which (PRED item) 
returns nil."
+  "Return the tail of LIST starting from the first item for which (PRED item) 
returns nil."
   (--drop-while (funcall pred it) list))
 
 (defun -split-at (n list)
-  "Returns a list of ((-take N LIST) (-drop N LIST)), in no more than one pass 
through the list."
+  "Return a list of ((-take N LIST) (-drop N LIST)), in no more than one pass 
through the list."
   (let (result)
     (--dotimes n
       (when list
@@ -552,17 +566,23 @@ The time complexity is O(n)."
     (append (-drop (- n) list) (-take (- n) list))))
 
 (defun -insert-at (n x list)
-  "Returns a list with X inserted into LIST at position N."
+  "Return a list with X inserted into LIST at position N.
+
+See also: `-splice', `-splice-list'"
   (let ((split-list (-split-at n list)))
     (nconc (car split-list) (cons x (cadr split-list)))))
 
 (defun -replace-at (n x list)
-  "Return a list with element at Nth position in LIST replaced with X."
+  "Return a list with element at Nth position in LIST replaced with X.
+
+See also: `-replace'"
   (let ((split-list (-split-at n list)))
     (nconc (car split-list) (cons x (cdr (cadr split-list))))))
 
 (defun -update-at (n func list)
-  "Return a list with element at Nth position in LIST replaced with `(func 
(nth n list))`."
+  "Return a list with element at Nth position in LIST replaced with `(func 
(nth n list))`.
+
+See also: `-map-when'"
   (let ((split-list (-split-at n list)))
     (nconc (car split-list) (cons (funcall func (car (cadr split-list))) (cdr 
(cadr split-list))))))
 
@@ -572,13 +592,17 @@ The time complexity is O(n)."
   `(-update-at ,n (lambda (it) ,form) ,list))
 
 (defun -remove-at (n list)
-  "Return a list with element at Nth position in LIST removed."
+  "Return a list with element at Nth position in LIST removed.
+
+See also: `-remove-at-indices', `-remove'"
   (-remove-at-indices (list n) list))
 
 (defun -remove-at-indices (indices list)
   "Return a list whose elements are elements from LIST without
 elements selected as `(nth i list)` for all i
-from INDICES."
+from INDICES.
+
+See also: `-remove-at', `-remove'"
   (let* ((indices (-sort '< indices))
          (diffs (cons (car indices) (-map '1- (-zip-with '- (cdr indices) 
indices))))
          r)
@@ -607,7 +631,7 @@ from INDICES."
        (list (nreverse ,r) ,l))))
 
 (defun -split-with (pred list)
-  "Returns a list of ((-take-while PRED LIST) (-drop-while PRED LIST)), in no 
more than one pass through the list."
+  "Return a list of ((-take-while PRED LIST) (-drop-while PRED LIST)), in no 
more than one pass through the list."
   (--split-with (funcall pred it) list))
 
 (defmacro -split-on (item list)
@@ -618,7 +642,7 @@ Empty lists are also removed from the result.
 
 Comparison is done by `equal'.
 
-See also `-split-when'."
+See also `-split-when'"
   (declare (debug (form form)))
   `(-split-when (lambda (it) (equal it ,item)) ,list))
 
@@ -655,7 +679,7 @@ This function can be thought of as a generalization of
        (list (nreverse ,y) (nreverse ,n)))))
 
 (defun -separate (pred list)
-  "Returns a list of ((-filter PRED LIST) (-remove PRED LIST)), in one pass 
through the list."
+  "Return a list of ((-filter PRED LIST) (-remove PRED LIST)), in one pass 
through the list."
   (--separate (funcall pred it) list))
 
 (defun ---partition-all-in-steps-reversed (n step list)
@@ -670,12 +694,12 @@ This function can be thought of as a generalization of
     result))
 
 (defun -partition-all-in-steps (n step list)
-  "Returns a new list with the items in LIST grouped into N-sized sublists at 
offsets STEP apart.
+  "Return a new list with the items in LIST grouped into N-sized sublists at 
offsets STEP apart.
 The last groups may contain less than N items."
   (nreverse (---partition-all-in-steps-reversed n step list)))
 
 (defun -partition-in-steps (n step list)
-  "Returns a new list with the items in LIST grouped into N-sized sublists at 
offsets STEP apart.
+  "Return a new list with the items in LIST grouped into N-sized sublists at 
offsets STEP apart.
 If there are not enough items to make the last group N-sized,
 those items are discarded."
   (let ((result (---partition-all-in-steps-reversed n step list)))
@@ -684,12 +708,12 @@ those items are discarded."
     (nreverse result)))
 
 (defun -partition-all (n list)
-  "Returns a new list with the items in LIST grouped into N-sized sublists.
+  "Return a new list with the items in LIST grouped into N-sized sublists.
 The last group may contain less than N items."
   (-partition-all-in-steps n n list))
 
 (defun -partition (n list)
-  "Returns a new list with the items in LIST grouped into N-sized sublists.
+  "Return a new list with the items in LIST grouped into N-sized sublists.
 If there are not enough items to make the last group N-sized,
 those items are discarded."
   (-partition-in-steps n n list))
@@ -722,7 +746,7 @@ those items are discarded."
            (nreverse ,r))))))
 
 (defun -partition-by (fn list)
-  "Applies FN to each item in LIST, splitting it each time FN returns a new 
value."
+  "Apply FN to each item in LIST, splitting it each time FN returns a new 
value."
   (--partition-by (funcall fn it) list))
 
 (defmacro --partition-by-header (form list)
@@ -757,8 +781,8 @@ those items are discarded."
            (nreverse ,r))))))
 
 (defun -partition-by-header (fn list)
-  "Applies FN to the first item in LIST. That is the header
-value. Applies FN to each item in LIST, splitting it each time FN
+  "Apply FN to the first item in LIST. That is the header
+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)."
   (--partition-by-header (funcall fn it) list))
@@ -797,7 +821,7 @@ elements of LIST.  Keys are compared by `equal'."
   (--group-by (funcall fn it) list))
 
 (defun -interpose (sep list)
-  "Returns a new list of all elements in LIST separated by SEP."
+  "Return a new list of all elements in LIST separated by SEP."
   (let (result)
     (when list
       (!cons (car list) result)
@@ -808,7 +832,7 @@ elements of LIST.  Keys are compared by `equal'."
     (nreverse result)))
 
 (defun -interleave (&rest lists)
-  "Returns a new list of the first item in each list, then the second etc."
+  "Return a new list of the first item in each list, then the second etc."
   (let (result)
     (while (-none? 'null lists)
       (--each lists (!cons (car it) result))
@@ -869,7 +893,7 @@ longest input list."
   (apply '-zip (apply '-pad (cons fill-value lists))))
 
 (defun -cycle (list)
-  "Returns an infinite copy of LIST that will cycle through the
+  "Return an infinite copy of LIST that will cycle through the
 elements and repeat from the beginning."
   (let ((newlist (-map 'identity list)))
     (nconc newlist newlist)))
@@ -882,7 +906,7 @@ will all have the same length."
     (--map (append (cdr it) (-repeat (- n (car it)) fill-value)) annotations)))
 
 (defun -annotate (fn list)
-  "Returns a list of cons cells where each cell is FN applied to each
+  "Return a list of cons cells where each cell is FN applied to each
 element of LIST paired with the unmodified element of LIST."
   (-zip (-map fn list) list))
 
@@ -918,7 +942,7 @@ The outer product is computed by applying fn to all possible
 combinations created by taking one element from each list in
 order.  The dimension of the result is (length lists).
 
-See also: `-table-flat'."
+See also: `-table-flat'"
   (let ((restore-lists (copy-sequence lists))
         (last-list (last lists))
         (re (--map nil (number-sequence 1 (length lists)))))
@@ -944,7 +968,7 @@ of the result.  This is equivalent to calling:
 
 but the implementation here is much more efficient.
 
-See also: `-flatten-n', `-table'."
+See also: `-flatten-n', `-table'"
   (let ((restore-lists (copy-sequence lists))
         (last-list (last lists))
         re)
@@ -955,8 +979,8 @@ See also: `-flatten-n', `-table'."
     (nreverse re)))
 
 (defun -partial (fn &rest args)
-  "Takes a function FN and fewer than the normal arguments to FN,
-and returns a fn that takes a variable number of additional ARGS.
+  "Take a function FN and fewer than the normal arguments to FN,
+and return a fn that takes a variable number of additional ARGS.
 When called, the returned function calls FN with ARGS first and
 then additional args."
   (apply 'apply-partially fn args))
@@ -1013,9 +1037,9 @@ as `(nth i list)` for all i from INDICES."
     (nreverse r)))
 
 (defmacro -> (x &optional form &rest more)
-  "Threads the expr through the forms. Inserts X as the second
-item in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+  "Thread the expr through the forms. Insert X as the second item
+in the first form, making a list of it if it is not a list
+already. If there are more forms, insert the first form as the
 second item in second form, etc."
   (cond
    ((null form) x)
@@ -1025,9 +1049,9 @@ second item in second form, etc."
    (:else `(-> (-> ,x ,form) ,@more))))
 
 (defmacro ->> (x form &rest more)
-  "Threads the expr through the forms. Inserts X as the last item
+  "Thread the expr through the forms. Insert X as the last item
 in the first form, making a list of it if it is not a list
-already. If there are more forms, inserts the first form as the
+already. If there are more forms, insert the first form as the
 last item in second form, etc."
   (if (null more)
       (if (listp form)
@@ -1036,10 +1060,10 @@ last item in second form, etc."
     `(->> (->> ,x ,form) ,@more)))
 
 (defmacro --> (x form &rest more)
-  "Threads the expr through the forms. Inserts X at the position
+  "Thread the expr through the forms. Insert X at the position
 signified by the token `it' in the first form. If there are more
-forms, inserts the first form at the position signified by `it'
-in in second form, etc."
+forms, insert the first form at the position signified by `it' in
+in second form, etc."
   (if (null more)
       (if (listp form)
           (--map-when (eq it 'it) x form)
@@ -1051,7 +1075,7 @@ in in second form, etc."
 (put '--> 'lisp-indent-function 1)
 
 (defun -grade-up (comparator list)
-  "Grades elements of LIST using COMPARATOR relation, yielding a
+  "Grade elements of LIST using COMPARATOR relation, yielding a
 permutation vector such that applying this permutation to LIST
 sorts it in ascending order."
   ;; ugly hack to "fix" lack of lexical scope
@@ -1061,7 +1085,7 @@ sorts it in ascending order."
       (-map 'cdr))))
 
 (defun -grade-down (comparator list)
-  "Grades elements of LIST using COMPARATOR relation, yielding a
+  "Grade elements of LIST using COMPARATOR relation, yielding a
 permutation vector such that applying this permutation to LIST
 sorts it in descending order."
   ;; ugly hack to "fix" lack of lexical scope
@@ -1145,6 +1169,8 @@ Alias: `-uniq'"
     (--each list (unless (-contains? result it) (!cons it result)))
     (nreverse result)))
 
+(defalias '-uniq '-distinct)
+
 (defun -union (list list2)
   "Return a new list containing the elements of LIST1 and elements of LIST2 
that are not in LIST1.
 The test for equality is done with `equal',
@@ -1154,8 +1180,6 @@ or with `-compare-fn' if that's non-nil."
     (--each list2 (unless (-contains? result it) (!cons it result)))
     (nreverse result)))
 
-(defalias '-uniq '-distinct)
-
 (defun -intersection (list list2)
   "Return a new list containing only the elements that are members of both 
LIST and LIST2.
 The test for equality is done with `equal',
@@ -1171,12 +1195,16 @@ or with `-compare-fn' if that's non-nil."
 (defvar -compare-fn nil
   "Tests for equality use this function or `equal' if this is nil.
 It should only be set using dynamic scope with a let, like:
-(let ((-compare-fn =)) (-union numbers1 numbers2 numbers3)")
+
+  (let ((-compare-fn =)) (-union numbers1 numbers2 numbers3)")
 
 (defun -contains? (list element)
-  "Return whether LIST contains ELEMENT.
-The test for equality is done with `equal',
-or with `-compare-fn' if that's non-nil."
+  "Return non-nil if LIST contains ELEMENT.
+
+The test for equality is done with `equal', or with `-compare-fn'
+if that's non-nil.
+
+Alias: `-contains-p'"
   (not
    (null
     (cond
@@ -1195,7 +1223,9 @@ or with `-compare-fn' if that's non-nil."
 (defun -same-items? (list list2)
   "Return true if LIST and LIST2 has the same items.
 
-The order of the elements in the lists does not matter."
+The order of the elements in the lists does not matter.
+
+Alias: `-same-items-p'"
   (let ((length-a (length list))
         (length-b (length list2)))
     (and
@@ -1205,19 +1235,25 @@ The order of the elements in the lists does not matter."
 (defalias '-same-items-p '-same-items?)
 
 (defun -is-prefix? (prefix list)
-  "Return non-nil if PREFIX is prefix of LIST."
+  "Return non-nil if PREFIX is prefix of LIST.
+
+Alias: `-is-prefix-p'"
   (--each-while list (equal (car prefix) it)
     (!cdr prefix))
   (not prefix))
 
 (defun -is-suffix? (suffix list)
-  "Return non-nil if SUFFIX is suffix of LIST."
+  "Return non-nil if SUFFIX is suffix of LIST.
+
+Alias: `-is-suffix-p'"
   (-is-prefix? (nreverse suffix) (nreverse list)))
 
 (defun -is-infix? (infix list)
   "Return non-nil if INFIX is infix of LIST.
 
-This operation runs in O(n^2) time"
+This operation runs in O(n^2) time
+
+Alias: `-is-infix-p'"
   (let (done)
     (while (and (not done) list)
       (setq done (-is-prefix? infix list))
@@ -1230,7 +1266,7 @@ This operation runs in O(n^2) time"
 
 (defun -sort (comparator list)
   "Sort LIST, stably, comparing elements using COMPARATOR.
-Returns the sorted list.  LIST is NOT modified by side effects.
+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."
   (sort (copy-sequence list) comparator))
@@ -1250,7 +1286,7 @@ not, return a list with ARGS as elements."
 
 (defun -repeat (n x)
   "Return a list with X repeated N times.
-Returns nil if N is less than 1."
+Return nil if N is less than 1."
   (let (ret)
     (--dotimes n (!cons x ret))
     ret))
diff --git a/dev/examples.el b/dev/examples.el
index 23697c2..edf627a 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -9,45 +9,33 @@
 (defun square (num) (* num num))
 (defun three-letters () '("A" "B" "C"))
 
-(def-example-group "List to list" nil
+(def-example-group "Maps"
+  "Functions in this category take a transforming function, which
+is then applied sequentially to each or selected elements of the
+input list.  The results are collected in order and returned as
+new list."
+
   (defexamples -map
     (-map (lambda (num) (* num num)) '(1 2 3 4)) => '(1 4 9 16)
     (-map 'square '(1 2 3 4)) => '(1 4 9 16)
     (--map (* it it) '(1 2 3 4)) => '(1 4 9 16)
     (--map (concat it it) (three-letters)) => '("AA" "BB" "CC"))
 
-  (defexamples -filter
-    (-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(2 4)
-    (-filter 'even? '(1 2 3 4)) => '(2 4)
-    (--filter (= 0 (% it 2)) '(1 2 3 4)) => '(2 4))
-
-  (defexamples -remove
-    (-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(1 3)
-    (-remove 'even? '(1 2 3 4)) => '(1 3)
-    (--remove (= 0 (% it 2)) '(1 2 3 4)) => '(1 3)
-    (let ((mod 2)) (-remove (lambda (num) (= 0 (% num mod))) '(1 2 3 4))) => 
'(1 3)
-    (let ((mod 2)) (--remove (= 0 (% it mod)) '(1 2 3 4))) => '(1 3))
-
-  (defexamples -keep
-    (-keep 'cdr '((1 2 3) (4 5) (6))) => '((2 3) (5))
-    (-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) => '(40 
50 60)
-    (--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) => '(40 50 60))
-
   (defexamples -map-when
     (-map-when 'even? 'square '(1 2 3 4)) => '(1 4 3 16)
     (--map-when (> it 2) (* it it) '(1 2 3 4)) => '(1 2 9 16)
     (--map-when (= it 2) 17 '(1 2 3 4)) => '(1 17 3 4)
     (-map-when (lambda (n) (= n 3)) (lambda (n) 0) '(1 2 3 4)) => '(1 2 0 4))
 
-  (defexamples -replace
-    (-replace 1 "1" '(1 2 3 4 3 2 1)) => '("1" 2 3 4 3 2 "1")
-    (-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) => 
'("a" "nice" "bar" "sentence" "about" "bar")
-    (-replace 1 2 nil) => nil)
-
   (defexamples -map-indexed
     (-map-indexed (lambda (index item) (- item index)) '(1 2 3 4)) => '(1 1 1 
1)
     (--map-indexed (- it it-index) '(1 2 3 4)) => '(1 1 1 1))
 
+  (defexamples -annotate
+    (-annotate '1+ '(1 2 3)) => '((2 . 1) (3 . 2) (4 . 3))
+    (-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) => '((5 . 
("h" "e" "l" "l" "o")) (2 . ("hello" "world")))
+    (--annotate (< 1 it) '(0 1 2 3)) => '((nil . 0) (nil . 1) (t . 2) (t . 3)))
+
   (defexamples -splice
     (-splice 'even? (lambda (x) (list x x)) '(1 2 3 4)) => '(1 2 2 3 4 4)
     (--splice 't (list it it) '(1 2 3 4)) => '(1 1 2 2 3 3 4 4)
@@ -57,29 +45,25 @@
     (-splice-list 'keywordp '(a b c) '(1 :foo 2)) => '(1 a b c 2)
     (-splice-list 'keywordp nil '(1 :foo 2)) => '(1 2))
 
-  (defexamples -flatten
-    (-flatten '((1))) => '(1)
-    (-flatten '((1 (2 3) (((4 (5))))))) => '(1 2 3 4 5)
-    (-flatten '(1 2 (3 . 4))) => '(1 2 (3 . 4)))
-
-  (defexamples -flatten-n
-    (-flatten-n 1 '((1 2) ((3 4) ((5 6))))) => '(1 2 (3 4) ((5 6)))
-    (-flatten-n 2 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 (5 6))
-    (-flatten-n 3 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 5 6)
-    (-flatten-n 0 '(3 4)) => '(3 4)
-    (-flatten-n 0 '((1 2) (3 4))) => '((1 2) (3 4))
-    (-flatten-n 0 '(((1 2) (3 4)))) => '(((1 2) (3 4))))
-
-  (defexamples -concat
-    (-concat '(1)) => '(1)
-    (-concat '(1) '(2)) => '(1 2)
-    (-concat '(1) '(2 3) '(4)) => '(1 2 3 4)
-    (-concat) => nil)
-
   (defexamples -mapcat
     (-mapcat 'list '(1 2 3)) => '(1 2 3)
     (-mapcat (lambda (item) (list 0 item)) '(1 2 3)) => '(0 1 0 2 0 3)
-    (--mapcat (list 0 it) '(1 2 3)) => '(0 1 0 2 0 3))
+    (--mapcat (list 0 it) '(1 2 3)) => '(0 1 0 2 0 3)))
+
+(def-example-group "Sublist selection"
+  "Functions returning a sublist of the original list."
+
+  (defexamples -filter
+    (-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(2 4)
+    (-filter 'even? '(1 2 3 4)) => '(2 4)
+    (--filter (= 0 (% it 2)) '(1 2 3 4)) => '(2 4))
+
+  (defexamples -remove
+    (-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) => '(1 3)
+    (-remove 'even? '(1 2 3 4)) => '(1 3)
+    (--remove (= 0 (% it 2)) '(1 2 3 4)) => '(1 3)
+    (let ((mod 2)) (-remove (lambda (num) (= 0 (% num mod))) '(1 2 3 4))) => 
'(1 3)
+    (let ((mod 2)) (--remove (= 0 (% it mod)) '(1 2 3 4))) => '(1 3))
 
   (defexamples -slice
     (-slice '(1 2 3 4 5) 1) => '(2 3 4 5)
@@ -116,9 +100,42 @@
     (-drop-while 'even? '(2 4 5 6)) => '(5 6)
     (--drop-while (< it 4) '(1 2 3 4 3 2 1)) => '(4 3 2 1))
 
-  (defexamples -rotate
-    (-rotate 3 '(1 2 3 4 5 6 7)) => '(5 6 7 1 2 3 4)
-    (-rotate -3 '(1 2 3 4 5 6 7)) => '(4 5 6 7 1 2 3))
+  (defexamples -select-by-indices
+    (-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" 
"t" "o" "r")) => '("c" "o" "l" "o" "r")
+    (-select-by-indices '(2 1 0) '("a" "b" "c")) => '("c" "b" "a")
+    (-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) => '("f" "a" 
"r" "f" "a" "l" "l" "a")))
+
+(def-example-group "List to list"
+  "Bag of various functions which modify input list."
+
+  (defexamples -keep
+    (-keep 'cdr '((1 2 3) (4 5) (6))) => '((2 3) (5))
+    (-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) => '(40 
50 60)
+    (--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) => '(40 50 60))
+
+  (defexamples -concat
+    (-concat '(1)) => '(1)
+    (-concat '(1) '(2)) => '(1 2)
+    (-concat '(1) '(2 3) '(4)) => '(1 2 3 4)
+    (-concat) => nil)
+
+  (defexamples -flatten
+    (-flatten '((1))) => '(1)
+    (-flatten '((1 (2 3) (((4 (5))))))) => '(1 2 3 4 5)
+    (-flatten '(1 2 (3 . 4))) => '(1 2 (3 . 4)))
+
+  (defexamples -flatten-n
+    (-flatten-n 1 '((1 2) ((3 4) ((5 6))))) => '(1 2 (3 4) ((5 6)))
+    (-flatten-n 2 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 (5 6))
+    (-flatten-n 3 '((1 2) ((3 4) ((5 6))))) => '(1 2 3 4 5 6)
+    (-flatten-n 0 '(3 4)) => '(3 4)
+    (-flatten-n 0 '((1 2) (3 4))) => '((1 2) (3 4))
+    (-flatten-n 0 '(((1 2) (3 4)))) => '(((1 2) (3 4))))
+
+  (defexamples -replace
+    (-replace 1 "1" '(1 2 3 4 3 2 1)) => '("1" 2 3 4 3 2 "1")
+    (-replace "foo" "bar" '("a" "nice" "foo" "sentence" "about" "foo")) => 
'("a" "nice" "bar" "sentence" "about" "bar")
+    (-replace 1 2 nil) => nil)
 
   (defexamples -insert-at
     (-insert-at 1 'x '(a b c)) => '(a x b c)
@@ -166,7 +183,9 @@
     (-remove-at-indices '(0) '(((a b) (c d) (e f g) h i ((j) k) l (m)))) => nil
     (-remove-at-indices '(2 3) '((0) (1) (2) (3) (4) (5) (6))) => '((0) (1) 
(4) (5) (6))))
 
-(def-example-group "Reductions" nil
+(def-example-group "Reductions"
+  "Functions reducing lists into single value."
+
   (defexamples -reduce-from
     (-reduce-from '- 10 '(1 2 3)) => 4
     (-reduce-from (lambda (memo item)
@@ -301,7 +320,9 @@
     (-is-infix? '(2 3 4) '(1 2 4 5)) => nil
     (-is-infix? '(2 4) '(1 2 3 4 5)) => nil))
 
-(def-example-group "Partitioning" nil
+(def-example-group "Partitioning"
+  "Functions partitioning the input list into a list of lists."
+
   (defexamples -split-at
     (-split-at 3 '(1 2 3 4 5)) => '((1 2 3) (4 5))
     (-split-at 17 '(1 2 3 4 5)) => '((1 2 3 4 5) nil))
@@ -372,7 +393,9 @@
     (-group-by 'even? '(1 1 2 2 2 3 4 6 8)) => '((nil . (1 1 3)) (t . (2 2 2 4 
6 8)))
     (--group-by (car (split-string it "/")) '("a/b" "c/d" "a/e")) => '(("a" . 
("a/b" "a/e")) ("c" . ("c/d")))))
 
-(def-example-group "Indexing" nil
+(def-example-group "Indexing"
+  "Return indices of elements based on predicates, sort elements by indices 
etc."
+
   (defexamples -elem-index
     (-elem-index 2 '(6 7 8 2 3 4)) => 3
     (-elem-index "bar" '("foo" "bar" "baz")) => 1
@@ -398,11 +421,6 @@
     (--find-indices (< 5 it) '(2 4 1 6 3 3 5 8)) => '(3 7)
     (-find-indices (-partial 'string-lessp "baz") '("bar" "foo" "baz")) => 
'(1))
 
-  (defexamples -select-by-indices
-    (-select-by-indices '(4 10 2 3 6) '("v" "e" "l" "o" "c" "i" "r" "a" "p" 
"t" "o" "r")) => '("c" "o" "l" "o" "r")
-    (-select-by-indices '(2 1 0) '("a" "b" "c")) => '("c" "b" "a")
-    (-select-by-indices '(0 1 2 0 1 3 3 1) '("f" "a" "r" "l")) => '("f" "a" 
"r" "f" "a" "l" "l" "a"))
-
   (defexamples -grade-up
     (-grade-up '< '(3 1 4 2 1 3 3)) => '(1 4 3 0 5 6 2)
     (let ((l '(3 1 4 2 1 3 3))) (-select-by-indices (-grade-up '< l) l)) => 
'(1 1 2 3 3 3 4))
@@ -411,7 +429,9 @@
     (-grade-down '< '(3 1 4 2 1 3 3)) => '(2 0 5 6 3 1 4)
     (let ((l '(3 1 4 2 1 3 3))) (-select-by-indices (-grade-down '< l) l)) => 
'(4 3 3 3 2 1 1)))
 
-(def-example-group "Set operations" nil
+(def-example-group "Set operations"
+  "Operations pretending lists are sets."
+
   (defexamples -union
     (-union '(1 2 3) '(3 4 5))  => '(1 2 3 4 5)
     (-union '(1 2 3 4) '())  => '(1 2 3 4)
@@ -431,7 +451,13 @@
     (-distinct '()) => '()
     (-distinct '(1 2 2 4)) => '(1 2 4)))
 
-(def-example-group "Other list operations" nil
+(def-example-group "Other list operations"
+  "Other list functions not fit to be classified elsewhere."
+
+  (defexamples -rotate
+    (-rotate 3 '(1 2 3 4 5 6 7)) => '(5 6 7 1 2 3 4)
+    (-rotate -3 '(1 2 3 4 5 6 7)) => '(4 5 6 7 1 2 3))
+
   (defexamples -repeat
     (-repeat 3 :a) => '(:a :a :a)
     (-repeat 1 :a) => '(:a)
@@ -490,11 +516,6 @@
     (-pad nil '(1 2 3) '(4 5) '(6 7 8 9 10)) => '((1 2 3 nil nil) (4 5 nil nil 
nil) (6 7 8 9 10))
     (-pad 0 '(1 2) '(3 4)) => '((1 2) (3 4)))
 
-  (defexamples -annotate
-    (-annotate '1+ '(1 2 3)) => '((2 . 1) (3 . 2) (4 . 3))
-    (-annotate 'length '(("h" "e" "l" "l" "o") ("hello" "world"))) => '((5 . 
("h" "e" "l" "l" "o")) (2 . ("hello" "world")))
-    (--annotate (< 1 it) '(0 1 2 3)) => '((nil . 0) (nil . 1) (t . 2) (t . 3)))
-
   (defexamples -table
     (-table '* '(1 2 3) '(1 2 3)) => '((1 2 3) (2 4 6) (3 6 9))
     (-table (lambda (a b) (-sum (-zip-with '* a b))) '((1 2) (3 4)) '((1 3) (2 
4))) => '((7 15) (10 22))
@@ -540,7 +561,9 @@
     (-list '(1 2 3) => '(1 2 3))
     (-list '((1) (2)) => '((1) (2)))))
 
-(def-example-group "Tree operations" nil
+(def-example-group "Tree operations"
+  "Functions pretending lists are trees."
+
   (defexamples -tree-map
     (-tree-map '1+ '(1 (2 3) (4 (5 6) 7))) => '(2 (3 4) (5 (6 7) 8))
     (-tree-map '(lambda (x) (cons x (expt 2 x))) '(1 (2 3) 4)) => '((1 . 2) 
((2 . 4) (3 . 8)) (4 . 16))
@@ -615,7 +638,9 @@
     (--> "def" (concat "abc" it "ghi") (upcase it)) => "ABCDEFGHI"
     (--> "def" (concat "abc" it "ghi") upcase) => "ABCDEFGHI"))
 
-(def-example-group "Binding" nil
+(def-example-group "Binding"
+  "Convenient versions of `let` and `let*` constructs combined with flow 
control."
+
   (defexamples -when-let
     (-when-let (match-index (string-match "d" "abcd")) (+ match-index 2)) => 5
     (--when-let (member :b '(:a :b :c)) (cons :d it)) => '(:d :b :c)
@@ -633,7 +658,9 @@
     (-if-let* ((x 5) (y 3) (z 7)) (+ x y z) "foo") => 15
     (-if-let* ((x 5) (y nil) (z 7)) (+ x y z) "foo") => "foo"))
 
-(def-example-group "Side-effects" nil
+(def-example-group "Side-effects"
+  "Functions iterating over lists for side-effect only."
+
   (defexamples -each
     (let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) => nil
     (let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s)))) s) => '(3 
2 1)
@@ -657,7 +684,9 @@
     (let ((l '(3))) (!cdr l) l) => '()
     (let ((l '(3 5))) (!cdr l) l) => '(5)))
 
-(def-example-group "Function combinators" "These combinators require Emacs 24 
for its lexical scope. So they are offered in a separate package: 
`dash-functional`."
+(def-example-group "Function combinators"
+  "These combinators require Emacs 24 for its lexical scope. So they are 
offered in a separate package: `dash-functional`."
+
   (defexamples -partial
     (funcall (-partial '- 5) 3) => 2
     (funcall (-partial '+ 5 2) 3) => 10)