fix: update docs

preparing to set up docstring validation

5 files changed, 137 insertions, 166 deletions

diff --git a/doc/cljlib.md b/doc/cljlib.md
index 54d8294..e54bcae 100644
--- a/doc/cljlib.md
+++ b/doc/cljlib.md
@@ -823,6 +823,7 @@ Map [`mul`](#mul) over two tables:
 Basic `zipmap` implementation:
 
 ``` fennel
+(import-macros {: into} :macros)
 (fn zipmap [keys vals]
   (into {} (mapv vector keys vals)))
 
@@ -1078,17 +1079,17 @@ Ordered sets are created by passing any amount of elements desired to
 be in the set:
 
 ``` fennel
->> (ordered-set)
-@set{}
->> (ordered-set :a :c :b)
-@set{:a :c :b}
+(ordered-set)
+;; => @set{}
+(ordered-set :a :c :b)
+;; => @set{:a :c :b}
 ```
 
 Duplicate items are not added:
 
 ``` fennel
->> (ordered-set :a :c :a :a :a :a :c :b)
-@set{:a :c :b}
+(ordered-set :a :c :a :a :a :a :c :b)
+;; => @set{:a :c :b}
 ```
 
 #### Check if set contains desired value:
@@ -1096,34 +1097,34 @@ Sets are functions of their keys, so simply calling a set with a
 desired key will either return the key, or `nil`:
 
 ``` fennel
->> (local oset (ordered-set [:a :b :c] [:c :d :e] :e :f))
->> (oset [:a :b :c])
-["a" "b" "c"]
->> (. oset :e)
-"e"
->> (oset [:a :b :f])
-nil
+(local oset (ordered-set [:a :b :c] [:c :d :e] :e :f))
+(oset [:a :b :c])
+;; => ["a" "b" "c"]
+(. oset :e)
+;; "e"
+(oset [:a :b :f])
+;; => nil
 ```
 
 #### Add items to existing set:
 To add element to the set use [`conj`](#conj) or `tset`
 
 ``` fennel
->> (local oset (ordered-set :a :b :c))
->> (conj oset :d :e)
-@set{:a :b :c :d :e}
+(local oset (ordered-set :a :b :c))
+(conj oset :d :e)
+;; => @set{:a :b :c :d :e}
 ```
 
 ##### Remove items from the set:
 To add element to the set use [`disj`](#disj) or `tset`
 
 ``` fennel
->> (local oset (ordered-set :a :b :c))
->> (disj oset :b)
-@set{:a :c}
->> (tset oset :a nil)
->> oset
-@set{:c}
+(local oset (ordered-set :a :b :c))
+(disj oset :b)
+;; => @set{:a :c}
+(tset oset :a nil)
+oset
+;; => @set{:c}
 ```
 
 #### Equality semantics
@@ -1132,12 +1133,9 @@ and are compared for having the same keys without particular order and
 same size:
 
 ``` fennel
->> (= (ordered-set :a :b) (ordered-set :b :a))
-true
->> (= (ordered-set :a :b) (ordered-set :b :a :c))
-false
->> (= (ordered-set :a :b) (hash-set :a :b))
-true
+(assert (= (ordered-set :a :b) (ordered-set :b :a)))
+(assert (not= (ordered-set :a :b) (ordered-set :b :a :c)))
+(assert (= (ordered-set :a :b) (hash-set :a :b)))
 ```
 
 ## `hash-set`
diff --git a/doc/macros.md b/doc/macros.md
index e9cc517..1841b14 100644
--- a/doc/macros.md
+++ b/doc/macros.md
@@ -18,7 +18,6 @@ Macros for Cljlib that implement various facilities from Clojure.
 - [`when-let`](#when-let)
 - [`if-some`](#if-some)
 - [`when-some`](#when-some)
-- [`deep-tostring`](#deep-tostring)
 
 ## `fn*`
 Function signature:
@@ -52,7 +51,7 @@ other one or more arguments:
   ([] nil)
   ([x & xs]
    (print x)
-   (f (unpack xs))))
+   (f ((or table.unpack _G.unpack) xs))))
 ```
 
 Note, that this function is recursive, and calls itself with less and
@@ -126,7 +125,7 @@ namespace tables:
 (fn* ns.strings.join
   ([s1 s2] (.. s1 s2))
   ([s1 s2 & strings]
-   (join (join s1 s2) (unpack strings)))) ;; call `join` resolves to ns.strings.join
+   (join (join s1 s2) ((or table.unpack _G.unpack) strings)))) ;; call `join` resolves to ns.strings.join
 
 (fn* ns.tables.join
   ([t1 t2]
@@ -135,14 +134,8 @@ namespace tables:
      (each [_ v (ipairs t2)] (table.insert res v))
      res))
   ([t1 t2 & tables]
-   (join (join t1 t2) (unpack tables)))) ;; call to `join` resolves to ns.tables.join
-```
+   (join (join t1 t2) ((or table.unpack _G.unpack) tables)))) ;; call to `join` resolves to ns.tables.join
 
-Note that this creates a collision and local `join` overrides `join`
-from `ns.strings`, so the latter must be fully qualified
-`ns.strings.join` when called outside of the function:
-
-``` fennel
 (ns.strings.join "a" "b" "c")
 ;; => abc
 (join ["a"] ["b"] ["c"] ["d" "e"])
@@ -151,6 +144,10 @@ from `ns.strings`, so the latter must be fully qualified
 ;; {}
 ```
 
+Note that this creates a collision and local `join` overrides `join`
+from `ns.strings`, so the latter must be fully qualified
+`ns.strings.join` when called outside of the function.
+
 ## `try`
 Function signature:
 
@@ -193,29 +190,30 @@ Catch all errors, ignore those and return fallback value:
 Catch error and do cleanup:
 
 ``` fennel
->> (let [tbl []]
-     (try
-       (table.insert tbl "a")
-       (table.insert tbl "b" "c")
-       (catch _
-         (each [k _ (pairs tbl)]
-           (tset tbl k nil))))
-     tbl)
-{}
+(let [tbl []]
+  (try
+    (table.insert tbl "a")
+    (table.insert tbl "b" "c")
+    (catch _
+      (each [k _ (pairs tbl)]
+        (tset tbl k nil))))
+  tbl)
+;; => {}
 ```
 
 Always run some side effect action:
 
 ``` fennel
->> (local res (try 10 (finally (print "side-effect!")))
-side-effect!
-nil
->> rese0
->> (local res (try (error 10) (catch 10 nil) (finally (print "side-effect!")))
-side-effect!
-nil
->> res
-nil
+(local res (try 10 (finally (print "side-effect!"))))
+;; => side-effect!
+;; => nil
+res
+;; => 10
+(local res (try (error 10) (catch 10 nil) (finally (print "side-effect!"))))
+;; => side-effect!
+;; => nil
+res
+;; => nil
 ```
 
 
@@ -247,7 +245,6 @@ supported, which is `:mutable`, which allows mutating variable with
 ``` fennel
 ;; Bad, will override existing documentation for 299792458 (if any)
 (def {:doc "speed of light in m/s"} c 299792458)
-(set c 0) ;; => error, can't mutate `c`
 
 (def :mutable address "Lua St.") ;; same as (def {:mutable true} address "Lua St.")
 (set address "Lisp St.") ;; can mutate `address`
@@ -357,19 +354,16 @@ tables to Lua's one:
                                    (.. "{" (table.concat res ", ") "}")))
 (defmethod to-lua-str :string [x] (.. "\"" x "\""))
 (defmethod to-lua-str :default [x] (tostring x))
-```
-
-And if we call it on some table, we'll get a valid Lua table:
 
-``` fennel
 (print (to-lua-str {:a {:b 10}}))
-;; prints {["a"] = {["b"] = 10}}
+;; => {["a"] = {["b"] = 10}}
 
 (print (to-lua-str [:a :b :c [:d {:e :f}]]))
-;; prints {[1] = "a", [2] = "b", [3] = "c", [4] = {[1] = "d", [2] = {["e"] = "f"}}}
+;; => {[1] = "a", [2] = "b", [3] = "c", [4] = {[1] = "d", [2] = {["e"] = "f"}}}
 ```
 
-Which we can then reformat as we want and use in Lua if we want.
+And if we call it on some table, we'll get a valid Lua table, which we
+can then reformat as we want and use in Lua if we want.
 
 ## `into`
 Function signature:
@@ -479,12 +473,12 @@ Attach metadata to a value.  When metadata feature is not enabled,
 returns the value without additional metadata.
 
 ``` fennel
->> (local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z)))
-                         {:fnl/arglist ["x" "y" "z" "..."]
-                          :fnl/docstring "sum first three values"}))
->> (doc foo)
-(foo x y z ...)
-  sum first three values
+(local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z)))
+                      {:fnl/arglist ["x" "y" "z" "..."]
+                       :fnl/docstring "sum first three values"}))
+;; (doc foo)
+;; => (foo x y z ...)
+;; =>   sum first three values
 ```
 
 ## `meta`
@@ -500,7 +494,7 @@ feature is not enabled returns `nil`.
 ### Example
 
 ``` fennel
->> (meta (with-meta {} {:meta "data"}))
+(meta (with-meta {} {:meta "data"}))
 ;; => {:meta "data"}
 ```
 
@@ -567,15 +561,6 @@ Function signature:
 If test is non-`nil`,
 evaluates `body` in implicit `do`.
 
-## `deep-tostring`
-Function signature:
-
-```
-(deep-tostring data key?)
-```
-
-**Undocumented**
-
 
 ---
 
diff --git a/init.fnl b/init.fnl
index 623120d..ee98456 100644
--- a/init.fnl
+++ b/init.fnl
@@ -750,6 +750,7 @@ Map [`mul`](#mul) over two tables:
 Basic `zipmap` implementation:
 
 ``` fennel
+(import-macros {: into} :macros)
 (fn zipmap [keys vals]
   (into {} (mapv vector keys vals)))
 
@@ -1192,17 +1193,17 @@ Ordered sets are created by passing any amount of elements desired to
 be in the set:
 
 ``` fennel
->> (ordered-set)
-@set{}
->> (ordered-set :a :c :b)
-@set{:a :c :b}
+(ordered-set)
+;; => @set{}
+(ordered-set :a :c :b)
+;; => @set{:a :c :b}
 ```
 
 Duplicate items are not added:
 
 ``` fennel
->> (ordered-set :a :c :a :a :a :a :c :b)
-@set{:a :c :b}
+(ordered-set :a :c :a :a :a :a :c :b)
+;; => @set{:a :c :b}
 ```
 
 ## Check if set contains desired value:
@@ -1210,34 +1211,34 @@ Sets are functions of their keys, so simply calling a set with a
 desired key will either return the key, or `nil`:
 
 ``` fennel
->> (local oset (ordered-set [:a :b :c] [:c :d :e] :e :f))
->> (oset [:a :b :c])
-[\"a\" \"b\" \"c\"]
->> (. oset :e)
-\"e\"
->> (oset [:a :b :f])
-nil
+(local oset (ordered-set [:a :b :c] [:c :d :e] :e :f))
+(oset [:a :b :c])
+;; => [\"a\" \"b\" \"c\"]
+(. oset :e)
+;; \"e\"
+(oset [:a :b :f])
+;; => nil
 ```
 
 ## Add items to existing set:
 To add element to the set use [`conj`](#conj) or `tset`
 
 ``` fennel
->> (local oset (ordered-set :a :b :c))
->> (conj oset :d :e)
-@set{:a :b :c :d :e}
+(local oset (ordered-set :a :b :c))
+(conj oset :d :e)
+;; => @set{:a :b :c :d :e}
 ```
 
 ### Remove items from the set:
 To add element to the set use [`disj`](#disj) or `tset`
 
 ``` fennel
->> (local oset (ordered-set :a :b :c))
->> (disj oset :b)
-@set{:a :c}
->> (tset oset :a nil)
->> oset
-@set{:c}
+(local oset (ordered-set :a :b :c))
+(disj oset :b)
+;; => @set{:a :c}
+(tset oset :a nil)
+oset
+;; => @set{:c}
 ```
 
 ## Equality semantics
@@ -1246,12 +1247,9 @@ and are compared for having the same keys without particular order and
 same size:
 
 ``` fennel
->> (= (ordered-set :a :b) (ordered-set :b :a))
-true
->> (= (ordered-set :a :b) (ordered-set :b :a :c))
-false
->> (= (ordered-set :a :b) (hash-set :a :b))
-true
+(assert (= (ordered-set :a :b) (ordered-set :b :a)))
+(assert (not= (ordered-set :a :b) (ordered-set :b :a :c)))
+(assert (= (ordered-set :a :b) (hash-set :a :b)))
 ```"
   [& xs]
   (let [Set (setmetatable {} {:__index deep-index})
diff --git a/macros.fnl b/macros.fnl
index 52a3a94..b045828 100644
--- a/macros.fnl
+++ b/macros.fnl
@@ -163,7 +163,7 @@ feature is not enabled returns `nil`.
 # Example
 
 ``` fennel
->> (meta (with-meta {} {:meta \"data\"}))
+(meta (with-meta {} {:meta \"data\"}))
 ;; => {:meta \"data\"}
 ```
 
@@ -196,12 +196,12 @@ this stuff will only work if you use `require-macros` instead of
 returns the value without additional metadata.
 
 ``` fennel
->> (local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z)))
-                         {:fnl/arglist [\"x\" \"y\" \"z\" \"...\"]
-                          :fnl/docstring \"sum first three values\"}))
->> (doc foo)
-(foo x y z ...)
-  sum first three values
+(local foo (with-meta (fn [...] (let [[x y z] [...]] (+ x y z)))
+                      {:fnl/arglist [\"x\" \"y\" \"z\" \"...\"]
+                       :fnl/docstring \"sum first three values\"}))
+;; (doc foo)
+;; => (foo x y z ...)
+;; =>   sum first three values
 ```"
   (if (not meta-enabled) value
       `(let [value# ,value
@@ -420,7 +420,7 @@ other one or more arguments:
   ([] nil)
   ([x & xs]
    (print x)
-   (f (unpack xs))))
+   (f ((or table.unpack _G.unpack) xs))))
 ```
 
 Note, that this function is recursive, and calls itself with less and
@@ -494,7 +494,7 @@ namespace tables:
 (fn* ns.strings.join
   ([s1 s2] (.. s1 s2))
   ([s1 s2 & strings]
-   (join (join s1 s2) (unpack strings)))) ;; call `join` resolves to ns.strings.join
+   (join (join s1 s2) ((or table.unpack _G.unpack) strings)))) ;; call `join` resolves to ns.strings.join
 
 (fn* ns.tables.join
   ([t1 t2]
@@ -503,21 +503,19 @@ namespace tables:
      (each [_ v (ipairs t2)] (table.insert res v))
      res))
   ([t1 t2 & tables]
-   (join (join t1 t2) (unpack tables)))) ;; call to `join` resolves to ns.tables.join
-```
-
-Note that this creates a collision and local `join` overrides `join`
-from `ns.strings`, so the latter must be fully qualified
-`ns.strings.join` when called outside of the function:
+   (join (join t1 t2) ((or table.unpack _G.unpack) tables)))) ;; call to `join` resolves to ns.tables.join
 
-``` fennel
 (ns.strings.join \"a\" \"b\" \"c\")
 ;; => abc
 (join [\"a\"] [\"b\"] [\"c\"] [\"d\" \"e\"])
 ;; => [\"a\" \"b\" \"c\" \"d\" \"e\"]
 (join \"a\" \"b\" \"c\")
 ;; {}
-```"
+```
+
+Note that this creates a collision and local `join` overrides `join`
+from `ns.strings`, so the latter must be fully qualified
+`ns.strings.join` when called outside of the function."
   (assert-compile (not (string? name)) "fn* expects symbol, vector, or list as first argument" name)
   (let [docstring (if (string? doc?) doc? nil)
         (name-wo-namespace namespaced?) (multisym->sym name)
@@ -933,19 +931,16 @@ tables to Lua's one:
                                    (.. \"{\" (table.concat res \", \") \"}\")))
 (defmethod to-lua-str :string [x] (.. \"\\\"\" x \"\\\"\"))
 (defmethod to-lua-str :default [x] (tostring x))
-```
 
-And if we call it on some table, we'll get a valid Lua table:
-
-``` fennel
 (print (to-lua-str {:a {:b 10}}))
-;; prints {[\"a\"] = {[\"b\"] = 10}}
+;; => {[\"a\"] = {[\"b\"] = 10}}
 
 (print (to-lua-str [:a :b :c [:d {:e :f}]]))
-;; prints {[1] = \"a\", [2] = \"b\", [3] = \"c\", [4] = {[1] = \"d\", [2] = {[\"e\"] = \"f\"}}}
+;; => {[1] = \"a\", [2] = \"b\", [3] = \"c\", [4] = {[1] = \"d\", [2] = {[\"e\"] = \"f\"}}}
 ```
 
-Which we can then reformat as we want and use in Lua if we want."})
+And if we call it on some table, we'll get a valid Lua table, which we
+can then reformat as we want and use in Lua if we want."})
 
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; def and defonce ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@@ -990,7 +985,6 @@ supported, which is `:mutable`, which allows mutating variable with
 ``` fennel
 ;; Bad, will override existing documentation for 299792458 (if any)
 (def {:doc \"speed of light in m/s\"} c 299792458)
-(set c 0) ;; => error, can't mutate `c`
 
 (def :mutable address \"Lua St.\") ;; same as (def {:mutable true} address \"Lua St.\")
 (set address \"Lisp St.\") ;; can mutate `address`
@@ -1129,30 +1123,30 @@ Catch all errors, ignore those and return fallback value:
 Catch error and do cleanup:
 
 ``` fennel
->> (let [tbl []]
-     (try
-       (table.insert tbl \"a\")
-       (table.insert tbl \"b\" \"c\")
-       (catch _
-         (each [k _ (pairs tbl)]
-           (tset tbl k nil))))
-     tbl)
-{}
+(let [tbl []]
+  (try
+    (table.insert tbl \"a\")
+    (table.insert tbl \"b\" \"c\")
+    (catch _
+      (each [k _ (pairs tbl)]
+        (tset tbl k nil))))
+  tbl)
+;; => {}
 ```
 
 Always run some side effect action:
 
 ``` fennel
->> (local res (try 10 (finally (print \"side-effect!\")))
-side-effect!
-nil
->> res
-10
->> (local res (try (error 10) (catch 10 nil) (finally (print \"side-effect!\")))
-side-effect!
-nil
->> res
-nil
+(local res (try 10 (finally (print \"side-effect!\"))))
+;; => side-effect!
+;; => nil
+res
+;; => 10
+(local res (try (error 10) (catch 10 nil) (finally (print \"side-effect!\"))))
+;; => side-effect!
+;; => nil
+res
+;; => nil
 ```
 "})
 
diff --git a/tests/test.fnl b/tests/test.fnl
index 143b749..f1d6371 100644
--- a/tests/test.fnl
+++ b/tests/test.fnl
@@ -42,23 +42,19 @@ Generates formatted message if `msg` is not set to other message.
 Compare two expressions:
 
 ``` fennel
->> (assert-eq 1 (+1 1))
-runtime error: equality assertion failed
-  Left: 1
-  Right: 3
+;; (assert-eq 1 (+1 1))
+;; => runtime error: equality assertion failed
+;; =>   Left: 1
+;; =>   Right: 3
 ```
 
 Deep compare values:
 
 ``` fennel
->> (assert-eq [1 {[2 3] [4 5 6]}] [1 {[2 3] [4 5]}])
-runtime error: equality assertion failed
-  Left: [1 {
-    [2 3] [4 5 6]
-  }]
-  Right: [1 {
-    [2 3] [4 5]
-  }]
+;; (assert-eq [1 {[2 3] [4 5 6]}] [1 {[2 3] [4 5]}])
+;; => runtime error: equality assertion failed
+;; =>   Left: [1 {[2 3] [4 5 6]}]
+;; =>   Right: [1 {[2 3] [4 5]}]
 ```"
   `(let [left# ,expr1
          right# ,expr2
@@ -89,8 +85,8 @@ runtime error: equality assertion failed
   verbose message if `msg` is not set.
 
 ``` fennel
->> (assert-is (= 1 2 3))
-runtime error: assertion failed for (= 1 2 3)
+;; (assert-is (= 1 2 3))
+;; => runtime error: assertion failed for (= 1 2 3)
 ```"
   `(assert ,expr
            (.. "assertion failed for "