From c83960871005881276a35eba1f75f50e88e0adf4 Mon Sep 17 00:00:00 2001
From: haithium <128622475+haithium@users.noreply.github.com>
Date: Sun, 22 Feb 2026 22:54:41 +0000
Subject: [PATCH] chore(docs): auto-generate docs

---
 docs/src/modules/list.md | 919 ++++++++++-----------------------------
 docs/src/modules/set.md  | 501 ++++++---------------
 2 files changed, 344 insertions(+), 1076 deletions(-)

diff --git a/docs/src/modules/list.md b/docs/src/modules/list.md
index bc104e6..0f5c2a6 100644
--- a/docs/src/modules/list.md
+++ b/docs/src/modules/list.md
@@ -1,6 +1,7 @@
 ---
-description:
-  Python-style List API for sequence mutation, querying, and transformations.
+desc:
+  "A Python-style list class providing common operations to create, modify, and
+  query sequences of values."
 ---
 
 # `List`
@@ -8,923 +9,443 @@ description:
 A Python-style list class providing common operations to create, modify, and
 query sequences of values.
 
-## Quick Reference
+## Usage
+
+```lua
+lsist = require "mods.List"
+
+ls = List({ "a" }):append("b")
+print(ls:contains("b")) --> true
+print(ls:index("b")) --> 2
+```
+
+## Functions
 
 **Predicates**:
 
-| Function                   | Description                                     |
-| -------------------------- | ----------------------------------------------- |
-| [`all(pred)`](#fn-allpred) | Return true if all values match the predicate.  |
-| [`any(pred)`](#fn-anypred) | Return true if any value matches the predicate. |
+| Function      | Description                                     |
+| ------------- | ----------------------------------------------- |
+| [`all`](#all) | Return true if all values match the predicate.  |
+| [`any`](#any) | Return true if any value matches the predicate. |
 
 **Mutation**:
 
-| Function                            | Description                                                          |
-| ----------------------------------- | -------------------------------------------------------------------- |
-| [`append(v)`](#fn-appendv)          | Append a value to the end of the list.                               |
-| [`clear()`](#fn-clear)              | Remove all elements from the list.                                   |
-| [`extend(ls)`](#fn-extendls)        | Extend the list with another list.                                   |
-| [`extract(pred)`](#fn-extractpred)  | Extract values matching the predicate and remove them from the list. |
-| [`insert(pos, v)`](#fn-insertpos-v) | Insert a value at the given position.                                |
-| [`insert(v)`](#fn-insertv)          | Append a value to the end of the list.                               |
-| [`pop()`](#fn-pop)                  | Remove and return the last element.                                  |
-| [`pop(pos)`](#fn-poppos)            | Remove and return the element at the given position.                 |
-| [`prepend(v)`](#fn-prependv)        | Insert a value at the start of the list.                             |
-| [`remove(v)`](#fn-removev)          | Remove the first matching value.                                     |
-| [`sort(comp)`](#fn-sortcomp)        | Sort the list in place.                                              |
+| Function              | Description                                                          |
+| --------------------- | -------------------------------------------------------------------- |
+| [`append`](#append)   | Append a value to the end of the list.                               |
+| [`clear`](#clear)     | Remove all elements from the list.                                   |
+| [`extend`](#extend)   | Extend the list with another list.                                   |
+| [`extract`](#extract) | Extract values matching the predicate and remove them from the list. |
+| [`insert`](#insert)   | Insert a value at the given position.                                |
+| [`insert`](#insert)   | Append a value to the end of the list.                               |
+| [`pop`](#pop)         | Remove and return the last element.                                  |
+| [`pop`](#pop)         | Remove and return the element at the given position.                 |
+| [`prepend`](#prepend) | Insert a value at the start of the list.                             |
+| [`remove`](#remove)   | Remove the first matching value.                                     |
+| [`sort`](#sort)       | Sort the list in place.                                              |
 
 **Copying**:
 
-| Function             | Description                        |
-| -------------------- | ---------------------------------- |
-| [`copy()`](#fn-copy) | Return a shallow copy of the list. |
+| Function        | Description                        |
+| --------------- | ---------------------------------- |
+| [`copy`](#copy) | Return a shallow copy of the list. |
 
 **Query**:
 
-| Function                             | Description                                                 |
-| ------------------------------------ | ----------------------------------------------------------- |
-| [`contains(v)`](#fn-containsv)       | Return true if the list contains the value.                 |
-| [`count(v)`](#fn-countv)             | Count how many times a value appears.                       |
-| [`index(v)`](#fn-indexv)             | Return the index of the first matching value.               |
-| [`index_if(pred)`](#fn-index_ifpred) | Return the index of the first value matching the predicate. |
-| [`len()`](#fn-len)                   | Return the number of elements in the list.                  |
+| Function                | Description                                                 |
+| ----------------------- | ----------------------------------------------------------- |
+| [`contains`](#contains) | Return true if the list contains the value.                 |
+| [`count`](#count)       | Count how many times a value appears.                       |
+| [`index`](#index)       | Return the index of the first matching value.               |
+| [`index_if`](#index-if) | Return the index of the first value matching the predicate. |
+| [`len`](#len)           | Return the number of elements in the list.                  |
 
 **Access**:
 
-| Function               | Description                               |
-| ---------------------- | ----------------------------------------- |
-| [`first()`](#fn-first) | Return the first element or nil if empty. |
-| [`last()`](#fn-last)   | Return the last element or nil if empty.  |
+| Function          | Description                                 |
+| ----------------- | ------------------------------------------- |
+| [`first`](#first) | Return the first element or `nil` if empty. |
+| [`last`](#last)   | Return the last element or `nil` if empty.  |
 
 **Transform**:
 
-| Function                                 | Description                                                        |
-| ---------------------------------------- | ------------------------------------------------------------------ |
-| [`difference(ls)`](#fn-differencels)     | Return a new list with values not in the given list.               |
-| [`drop(n)`](#fn-dropn)                   | Return a new list without the first n elements.                    |
-| [`filter(pred)`](#fn-filterpred)         | Return a new list with values matching the predicate.              |
-| [`flatten()`](#fn-flatten)               | Flatten one level of nested lists.                                 |
-| [`foreach(fn)`](#fn-foreachfn)           | Apply a function to each element (for side effects).               |
-| [`group_by(fn)`](#fn-group_byfn)         | Group list values by a computed key.                               |
-| [`intersection(ls)`](#fn-intersectionls) | Return values that are also present in the given list.             |
-| [`invert()`](#fn-invert)                 | Invert values to indices in a new table.                           |
-| [`join(sep)`](#fn-joinsep)               | Join list values into a string.                                    |
-| [`map(fn)`](#fn-mapfn)                   | Return a new list by mapping each value.                           |
-| [`reduce(fn, init)`](#fn-reducefn-init)  | Reduce the list to a single value using an accumulator.            |
-| [`reverse()`](#fn-reverse)               | Return a new list with items reversed.                             |
-| [`setify()`](#fn-setify)                 | Convert the list to a set.                                         |
-| [`slice(i, j)`](#fn-slicei-j)            | Return a new list containing items from i to j (inclusive).        |
-| [`take(n)`](#fn-taken)                   | Return the first n elements as a new list.                         |
-| [`uniq()`](#fn-uniq)                     | Return a new list with duplicates removed (first occurrence kept). |
-| [`zip(ls)`](#fn-zipls)                   | Zip two lists into a list of 2-element tables.                     |
-
-## Functions
+| Function                        | Description                                                                                       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| [`difference`](#difference)     | Return a new list with values not in the given list.                                              |
+| [`drop`](#drop)                 | Return a new list without the first n elements.                                                   |
+| [`filter`](#filter)             | Return a new list with values matching the predicate.                                             |
+| [`flatten`](#flatten)           | Flatten one level of nested lists.                                                                |
+| [`foreach`](#foreach)           | Apply a function to each element (for side effects). Returns nil.                                 |
+| [`group_by`](#group-by)         | Group list values by a computed key.                                                              |
+| [`intersection`](#intersection) | Return values that are also present in the given list. Order is preserved from the original list. |
+| [`invert`](#invert)             | Invert values to indices in a new table.                                                          |
+| [`join`](#join)                 | Join list values into a string.                                                                   |
+| [`map`](#map)                   | Return a new list by mapping each value.                                                          |
+| [`reduce`](#reduce)             | Reduce the list to a single value using an accumulator.                                           |
+| [`reverse`](#reverse)           | Return a new list with items reversed.                                                            |
+| [`setify`](#setify)             | Convert the list to a set.                                                                        |
+| [`slice`](#slice)               | Return a new list containing items from i to j (inclusive).                                       |
+| [`take`](#take)                 | Return the first n elements as a new list.                                                        |
+| [`uniq`](#uniq)                 | Return a new list with duplicates removed (first occurrence kept).                                |
+| [`zip`](#zip)                   | Zip two lists into a list of 2-element tables.                                                    |
 
 ### Predicates
 
-#### `all(pred)` {#fn-allpred}
+Boolean checks for list-wide conditions.
 
-Return true if all values match the predicate. Empty lists return true.
+#### `all`
 
-::: code-group
+Return true if all values match the predicate.
 
-```lua [example.lua]
-local is_even = function(v) return v % 2 == 0 end
-local ok = List({ 2, 4 }):all(is_even)
--- result: true
+```lua
+is_even = function(v) return v % 2 == 0 end
+ok = List({ 2, 4 }):all(is_even) --> true
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param pred fun(v:any):boolean
----@return boolean
----@nodiscard
-function all(pred) end
-```
+> [!NOTE] Empty lists return `true`.
 
-:::
-
-#### `any(pred)` {#fn-anypred}
+#### `any`
 
 Return true if any value matches the predicate.
 
-::: code-group
-
-```lua [example.lua]
-local has_len_2 = function(v) return #v == 2 end
-local ok = List({ "a", "bb" }):any(has_len_2)
--- result: true
+```lua
+has_len_2 = function(v) return #v == 2 end
+ok = List({ "a", "bb" }):any(has_len_2) --> true
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param pred fun(v:any):boolean
----@return boolean
----@nodiscard
-function any(pred) end
-```
-
-:::
-
 ### Mutation
 
-#### `append(v)` {#fn-appendv}
-
-Append a value to the end of the list.
+In-place operations that modify the current list.
 
-::: code-group
+#### `append`
 
-```lua [example.lua]
-local l = List({ "a" }):append("b")
--- result: { "a", "b" }
-```
+Append a value to the end of the list.
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return T self
-function append(v) end
+```lua
+ls = List({ "a" }):append("b") --> { "a", "b" }
 ```
 
-:::
-
-#### `clear()` {#fn-clear}
+#### `clear`
 
 Remove all elements from the list.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a", "b" }):clear()
--- result: { }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return T self
-function clear() end
+```lua
+ls = List({ "a", "b" }):clear() --> { }
 ```
 
-:::
-
-#### `extend(ls)` {#fn-extendls}
+#### `extend`
 
 Extend the list with another list.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a" })
-l:extend({ "b", "c" })
--- result: { "a", "b", "c" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param ls any[]
----@return T self
-function extend(ls) end
+```lua
+ls = List({ "a" }):extend({ "b", "c" }) --> { "a", "b", "c" }
 ```
 
-:::
-
-#### `extract(pred)` {#fn-extractpred}
+#### `extract`
 
 Extract values matching the predicate and remove them from the list.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a", "bb", "c" })
-local is_len_1 = function(v) return #v == 1 end
-local ex = l:extract(is_len_1)
--- result: ex = { "a", "c" }, l = { "bb" }
+```lua
+ls = List({ "a", "bb", "c" })
+is_len_1 = function(v) return #v == 1 end
+ex = ls:extract(is_len_1) --> ex = { "a", "c" }, ls = { "bb" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param pred fun(v:any):boolean
----@return T self
----@nodiscard
-function extract(pred) end
-```
-
-:::
-
-#### `insert(pos, v)` {#fn-insertpos-v}
+#### `insert`
 
 Insert a value at the given position.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a", "c" }):insert(2, "b")
--- result: { "a", "b", "c" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param pos integer
----@param v any
----@return T self
-function insert(pos, v) end
+```lua
+ls = List({ "a", "c" }):insert(2, "b") --> { "a", "b", "c" }
 ```
 
-:::
-
-#### `insert(v)` {#fn-insertv}
+#### `insert`
 
 Append a value to the end of the list.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a", "b" }):insert("b")
--- result: { "a", "b", "c" }
+```lua
+ls = List({ "a", "b" }):insert("b") --> { "a", "b", "c" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param v any
----@return T self
-function insert(v) end
-```
-
-:::
-
-#### `pop()` {#fn-pop}
+#### `pop`
 
 Remove and return the last element.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a", "b" })
-local v = l:pop()
--- result: v == "b"; l is { "a" }
+```lua
+ls = List({ "a", "b" })
+v = ls:pop() --> v == "b"; ls is { "a" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return any
-function pop() end
-```
-
-:::
-
-#### `pop(pos)` {#fn-poppos}
+#### `pop`
 
 Remove and return the element at the given position.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a", "b", "c" })
-local v = l:pop(2)
--- result: v == "b"; l is { "a", "c" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param pos integer
----@return any
-function pop(pos) end
+```lua
+ls = List({ "a", "b", "c" })
+v = ls:pop(2) --> v == "b"; ls is { "a", "c" }
 ```
 
-:::
-
-#### `prepend(v)` {#fn-prependv}
+#### `prepend`
 
 Insert a value at the start of the list.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "b", "c" })
-l:prepend("a")
--- result: { "a", "b", "c" }
+```lua
+ls = List({ "b", "c" })
+ls:prepend("a") --> { "a", "b", "c" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param v any
----@return T self
-function prepend(v) end
-```
-
-:::
-
-#### `remove(v)` {#fn-removev}
+#### `remove`
 
 Remove the first matching value.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ "a", "b", "b" })
-l:remove("b")
--- result: { "a", "b" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param v any
----@return T self
-function remove(v) end
+```lua
+ls = List({ "a", "b", "b" })
+ls:remove("b") --> { "a", "b" }
 ```
 
-:::
-
-#### `sort(comp)` {#fn-sortcomp}
+#### `sort`
 
 Sort the list in place.
 
-::: code-group
-
-```lua [example.lua]
-local l = List({ 3, 1, 2 })
-l:sort()
--- result: { 1, 2, 3 }
+```lua
+ls = List({ 3, 1, 2 })
+ls:sort() --> { 1, 2, 3 }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param comp? fun(a,b):boolean
----@return T self
-function sort(comp) end
-```
-
-:::
-
 ### Copying
 
-#### `copy()` {#fn-copy}
-
-Return a shallow copy of the list.
+Operations that return copied list data.
 
-::: code-group
+#### `copy`
 
-```lua [example.lua]
-local c = List({ "a", "b" }):copy()
--- result: { "a", "b" }
-```
+Return a shallow copy of the list.
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return T ls
----@nodiscard
-function copy() end
+```lua
+c = List({ "a", "b" }):copy() --> { "a", "b" }
 ```
 
-:::
-
 ### Query
 
-#### `contains(v)` {#fn-containsv}
-
-Return true if the list contains the value.
+Read-only queries for membership, counts, and indices.
 
-::: code-group
+#### `contains`
 
-```lua [example.lua]
-local ok = List({ "a", "b" }):contains("b")
--- result: true
-```
+Return true if the list contains the value.
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param v any
----@return any
----@nodiscard
-function contains(v) end
+```lua
+ok = List({ "a", "b" }):contains("b") --> true
 ```
 
-:::
-
-#### `count(v)` {#fn-countv}
+#### `count`
 
 Count how many times a value appears.
 
-::: code-group
-
-```lua [example.lua]
-local n = List({ "a", "b", "b" }):count("b")
--- result: 2
+```lua
+n = List({ "a", "b", "b" }):count("b") --> 2
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return integer
----@nodiscard
-function count(v) end
-```
-
-:::
-
-#### `index(v)` {#fn-indexv}
+#### `index`
 
 Return the index of the first matching value.
 
-::: code-group
-
-```lua [example.lua]
-local i = List({ "a", "b", "c", "b" }):index("b")
--- result: 2
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param v any
----@return any value
----@return integer? index
----@nodiscard
-function index(v) end
+```lua
+i = List({ "a", "b", "c", "b" }):index("b") --> 2
 ```
 
-:::
-
-#### `index_if(pred)` {#fn-index_ifpred}
+#### `index_if`
 
 Return the index of the first value matching the predicate.
 
-::: code-group
-
-```lua [example.lua]
-local gt_1 = function(x) return x > 1 end
-local i = List({ 1, 2, 3 }):index_if(gt_1)
--- result: 2
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param pred fun(v:any):boolean
----@return integer? index
----@nodiscard
-function index_if(pred) end
+```lua
+gt_1 = function(x) return x > 1 end
+i = List({ 1, 2, 3 }):index_if(gt_1) --> 2
 ```
 
-:::
-
-#### `len()` {#fn-len}
+#### `len`
 
 Return the number of elements in the list.
 
-::: code-group
-
-```lua [example.lua]
-local n = List({ "a", "b", "c" }):len()
--- result: 3
+```lua
+n = List({ "a", "b", "c" }):len() --> 3
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return integer
----@nodiscard
-function len() end
-```
-
-:::
+> [!NOTE] Uses Lua's `#` operator, so length is reliable for contiguous
+> array-like lists.
 
 ### Access
 
-#### `first()` {#fn-first}
-
-Return the first element or nil if empty.
+Direct element access helpers.
 
-::: code-group
+#### `first`
 
-```lua [example.lua]
-local v = List({ "a", "b" }):first()
--- result: "a"
-```
+Return the first element or `nil` if empty.
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return any
----@nodiscard
-function first() end
+```lua
+v = List({ "a", "b" }):first() --> "a"
 ```
 
-:::
-
-#### `last()` {#fn-last}
-
-Return the last element or nil if empty.
+#### `last`
 
-::: code-group
-
-```lua [example.lua]
-local v = List({ "a", "b" }):last()
--- result: "b"
-```
+Return the last element or `nil` if empty.
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return any
----@nodiscard
-function last() end
+```lua
+v = List({ "a", "b" }):last() --> "b"
 ```
 
-:::
-
 ### Transform
 
-#### `difference(ls)` {#fn-differencels}
-
-Return a new list with values not in the given list.
+Non-mutating transformations and derived-list operations.
 
-::: code-group
+#### `difference`
 
-```lua [example.lua]
-local d = List({ "a", "b", "c" }):difference({ "b" })
--- result: { "a", "c" }
-```
+Return a new list with values not in the given list.
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return T ls
----@nodiscard
-function difference(ls) end
+```lua
+d = List({ "a", "b", "c" }):difference({ "b" }) --> { "a", "c" }
 ```
 
-:::
-
-#### `drop(n)` {#fn-dropn}
+#### `drop`
 
 Return a new list without the first n elements.
 
-::: code-group
-
-```lua [example.lua]
-local t = List({ "a", "b", "c" }):drop(1)
--- result: { "b", "c" }
+```lua
+t = List({ "a", "b", "c" }):drop(1) --> { "b", "c" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param n integer
----@return T ls
----@nodiscard
-function drop(n) end
-```
-
-:::
-
-#### `filter(pred)` {#fn-filterpred}
+#### `filter`
 
 Return a new list with values matching the predicate.
 
-::: code-group
-
-```lua [example.lua]
-local is_len_1 = function(v) return #v == 1 end
-local f = List({ "a", "bb", "c" }):filter(is_len_1)
--- result: { "a", "c" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param pred fun(v:any):boolean
----@return T ls
----@nodiscard
-function filter(pred) end
+```lua
+is_len_1 = function(v) return #v == 1 end
+f = List({ "a", "bb", "c" }):filter(is_len_1) --> { "a", "c" }
 ```
 
-:::
-
-#### `flatten()` {#fn-flatten}
+#### `flatten`
 
 Flatten one level of nested lists.
 
-::: code-group
-
-```lua [example.lua]
-local f = List({ { "a", "b" }, { "c" } }):flatten()
--- result: { "a", "b", "c" }
+```lua
+f = List({ { "a", "b" }, { "c" } }):flatten() --> { "a", "b", "c" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return T self
----@nodiscard
-function flatten() end
-```
-
-:::
-
-#### `foreach(fn)` {#fn-foreachfn}
+#### `foreach`
 
 Apply a function to each element (for side effects). Returns nil.
 
-::: code-group
-
-```lua [example.lua]
+```lua
 List({ "a", "b" }):foreach(print)
+--> prints -> a
+--> prints -> b
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param fn fun(v:any)
----@return nil
-function foreach(fn) end
-```
-
-:::
-
-#### `group_by(fn)` {#fn-group_byfn}
+#### `group_by`
 
 Group list values by a computed key.
 
-::: code-group
-
-```lua [example.lua]
-local words = { "aa", "b", "ccc", "dd" }
-local g = List(words):group_by(string.len)
--- result: { {"b"}, { "aa", "dd" }, { "ccc" } }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param fn fun(v:any):any
----@return table<any, T>
----@nodiscard
-function group_by(fn) end
+```lua
+words = { "aa", "b", "ccc", "dd" }
+g = List(words):group_by(string.len) --> { {"b"}, { "aa", "dd" }, { "ccc" } }
 ```
 
-:::
-
-#### `intersection(ls)` {#fn-intersectionls}
+#### `intersection`
 
 Return values that are also present in the given list. Order is preserved from
 the original list.
 
-::: code-group
-
-```lua [example.lua]
-local i = List({ "a", "b", "a", "c" }):intersection({ "a", "c" })
--- result: { "a", "a", "c" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param ls T
----@return T self
----@nodiscard
-function intersection(ls) end
+```lua
+i = List({ "a", "b", "a", "c" }):intersection({ "a", "c" })
+--> { "a", "a", "c" }
 ```
 
-:::
-
-#### `invert()` {#fn-invert}
+#### `invert`
 
 Invert values to indices in a new table.
 
-::: code-group
-
-```lua [example.lua]
-local t = List({ "a", "b", "c" }):invert()
--- result: { a = 1, b = 2, c = 3 }
+```lua
+t = List({ "a", "b", "c" }):invert() --> { a = 1, b = 2, c = 3 }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return table
----@nodiscard
-function invert() end
-```
-
-:::
-
-#### `join(sep)` {#fn-joinsep}
+#### `join`
 
 Join list values into a string.
 
-::: code-group
-
-```lua [example.lua]
-local s = List({ "a", "b", "c" }):join(",")
--- result: "a,b,c"
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param sep? string
----@return string
----@nodiscard
-function join(sep) end
+```lua
+s = List({ "a", "b", "c" }):join(",") --> "a,b,c"
 ```
 
-:::
-
-#### `map(fn)` {#fn-mapfn}
+#### `map`
 
 Return a new list by mapping each value.
 
-::: code-group
-
-```lua [example.lua]
-local to_upper = function(v) return v:upper() end
-local m = List({ "a", "b" }):map(to_upper)
--- result: { "A", "B" }
+```lua
+to_upper = function(v) return v:upper() end
+m = List({ "a", "b" }):map(to_upper) --> { "A", "B" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param fn fun(v):any
----@return T ls
----@nodiscard
-function map(fn) end
-```
-
-:::
-
-#### `reduce(fn, init)` {#fn-reducefn-init}
-
-Reduce the list to a single value using an accumulator. If init is nil, the
-first element is used as the initial value. Empty lists return init (or nil if
-init is nil).
-
-::: code-group
+#### `reduce`
 
-```lua [example.lua]
-local add = function(acc, v) return acc + v end
-local sum = List({ 1, 2, 3 }):reduce(add, 0)
--- result: 6
+Reduce the list to a single value using an accumulator.
 
-sum = List({ 1, 2, 3 }):reduce(add, 10)
--- result: 16
+```lua
+add = function(acc, v) return acc + v end
+sum = List({ 1, 2, 3 }):reduce(add, 0) --> 6
+sum = List({ 1, 2, 3 }):reduce(add, 10) --> 16
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param fn fun(acc:any, v:any):any
----@param init? any
----@return any
----@nodiscard
-function reduce(fn, init) end
-```
-
-:::
+> [!NOTE]
+>
+> If init is `nil`, the first element is used as the initial value. Empty lists
+> return init (or `nil` if init is `nil`).
 
-#### `reverse()` {#fn-reverse}
+#### `reverse`
 
 Return a new list with items reversed.
 
-::: code-group
-
-```lua [example.lua]
-local r = List({ "a", "b", "c" }):reverse()
--- result: { "c", "b", "a" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return T ls
----@nodiscard
-function reverse() end
+```lua
+r = List({ "a", "b", "c" }):reverse() --> { "c", "b", "a" }
 ```
 
-:::
-
-#### `setify()` {#fn-setify}
+#### `setify`
 
 Convert the list to a set.
 
-::: code-group
-
-```lua [example.lua]
-local s = List({ "a", "b", "a" }):setify()
--- result: { a = true, b = true }
+```lua
+s = List({ "a", "b", "a" }):setify() --> { a = true, b = true }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return mods.Set|table<any,true>
----@nodiscard
-function setify() end
-```
-
-:::
-
-#### `slice(i, j)` {#fn-slicei-j}
+#### `slice`
 
-Return a new list containing items from i to j (inclusive). Supports negative
-indices (-1 is last element).
+Return a new list containing items from i to j (inclusive).
 
-::: code-group
-
-```lua [example.lua]
-local t = List({ "a", "b", "c", "d" }):slice(2, 3)
--- result: { "b", "c" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param i? integer
----@param j? integer
----@return T ls
----@nodiscard
-function slice(i, j) end
+```lua
+t = List({ "a", "b", "c", "d" }):slice(2, 3) --> { "b", "c" }
 ```
 
-:::
+> [!NOTE] Supports negative indices (-1 is last element).
 
-#### `take(n)` {#fn-taken}
+#### `take`
 
 Return the first n elements as a new list.
 
-::: code-group
-
-```lua [example.lua]
-local t = List({ "a", "b", "c" }):take(2)
--- result: { "a", "b" }
+```lua
+t = List({ "a", "b", "c" }):take(2) --> { "a", "b" }
 ```
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param n integer
----@return T ls
----@nodiscard
-function take(n) end
-```
-
-:::
-
-#### `uniq()` {#fn-uniq}
+#### `uniq`
 
 Return a new list with duplicates removed (first occurrence kept).
 
-::: code-group
-
-```lua [example.lua]
-local u = List({ "a", "b", "a", "c" }):uniq()
--- result: { "a", "b", "c" }
-```
-
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@return T ls
----@nodiscard
-function uniq() end
+```lua
+u = List({ "a", "b", "a", "c" }):uniq() --> { "a", "b", "c" }
 ```
 
-:::
+#### `zip`
 
-#### `zip(ls)` {#fn-zipls}
-
-Zip two lists into a list of 2-element tables. Length is the minimum of both
-lists.
-
-::: code-group
-
-```lua [example.lua]
-local z = List({ "a", "b" }):zip({ 1, 2 })
--- result: { {"a",1}, {"b",2} }
-```
+Zip two lists into a list of 2-element tables.
 
-```lua [signature.lua]
----@generic T:mods.List|any[]
----@param self T
----@param ls T
----@return T ls
----@nodiscard
-function zip(ls) end
+```lua
+z = List({ "a", "b" }):zip({ 1, 2 }) --> { {"a",1}, {"b",2} }
 ```
 
-:::
+> [!NOTE] Length is the minimum of both lists.
diff --git a/docs/src/modules/set.md b/docs/src/modules/set.md
index a2031d9..d7fc972 100644
--- a/docs/src/modules/set.md
+++ b/docs/src/modules/set.md
@@ -1,6 +1,7 @@
 ---
-description:
-  Python-style Set API for unique-value operations, predicates, and set algebra.
+desc:
+  "A Python-style set class providing common operations to create, modify, and
+  query collections of unique values."
 ---
 
 # `Set`
@@ -8,505 +9,251 @@ description:
 A Python-style set class providing common operations to create, modify, and
 query collections of unique values.
 
-## Quick Reference
+## Usage
 
-**Mutation**:
+```lua
+Set = require "mods.Set"
 
-| Function                                                                 | Description                                                 |
-| ------------------------------------------------------------------------ | ----------------------------------------------------------- |
-| [`add(v)`](#fn-addv)                                                     | Add an element to the set.                                  |
-| [`clear()`](#fn-clear)                                                   | Remove all elements from the set.                           |
-| [`difference_update(set)`](#fn-difference_updateset)                     | Remove elements found in another set (in place).            |
-| [`discard(v)`](#fn-discardv)                                             | Remove an element if present, do nothing otherwise.         |
-| [`intersection_update(set)`](#fn-intersection_updateset)                 | Keep only elements common to both sets (in place).          |
-| [`pop()`](#fn-pop)                                                       | Remove and return an arbitrary element.                     |
-| [`symmetric_difference_update(set)`](#fn-symmetric_difference_updateset) | Update the set with elements not shared by both (in place). |
-| [`update(set)`](#fn-updateset)                                           | Add all elements from another set (in place).               |
+s = Set({ "a" })
+print(s:contains("a")) --> true
+```
 
-**Copying**:
+## Functions
+
+**Mutation**:
 
-| Function             | Description                       |
-| -------------------- | --------------------------------- |
-| [`copy()`](#fn-copy) | Return a shallow copy of the set. |
+| Function                                                      | Description                                                 |
+| ------------------------------------------------------------- | ----------------------------------------------------------- |
+| [`add`](#add)                                                 | Add an element to the set.                                  |
+| [`clear`](#clear)                                             | Remove all elements from the set.                           |
+| [`difference_update`](#difference-update)                     | Remove elements found in another set (in place).            |
+| [`discard`](#discard)                                         | Remove an element if present, do nothing otherwise.         |
+| [`intersection_update`](#intersection-update)                 | Keep only elements common to both sets (in place).          |
+| [`pop`](#pop)                                                 | Remove and return an arbitrary element.                     |
+| [`symmetric_difference_update`](#symmetric-difference-update) | Update the set with elements not shared by both (in place). |
+| [`update`](#update)                                           | Add all elements from another set (in place).               |
 
-**Set Operations**:
+**Copying**:
 
-| Function                                                   | Description                                     |
-| ---------------------------------------------------------- | ----------------------------------------------- |
-| [`difference(set)`](#fn-differenceset)                     | Return elements in this set but not in another. |
-| [`intersection(set)`](#fn-intersectionset)                 | Return elements common to both sets.            |
-| [`symmetric_difference(set)`](#fn-symmetric_differenceset) | Return elements not shared by both sets.        |
-| [`union(set)`](#fn-unionset)                               | Return a new set with all elements from both.   |
+| Function                                        | Description                                     |
+| ----------------------------------------------- | ----------------------------------------------- |
+| [`copy`](#copy)                                 | Return a shallow copy of the set.               |
+| [`difference`](#difference)                     | Return elements in this set but not in another. |
+| [`intersection`](#intersection)                 | Return elements common to both sets.            |
+| [`symmetric_difference`](#symmetric-difference) | Return elements not shared by both sets.        |
+| [`union`](#union)                               | Return a new set with all elements from both.   |
 
 **Predicates**:
 
-| Function                               | Description                                                      |
-| -------------------------------------- | ---------------------------------------------------------------- |
-| [`isdisjoint(set)`](#fn-isdisjointset) | Return true if sets have no elements in common.                  |
-| [`isempty()`](#fn-isempty)             | Return true if the set has no elements.                          |
-| [`issubset(set)`](#fn-issubsetset)     | Return true if all elements of this set are also in another set. |
-| [`issuperset(set)`](#fn-issupersetset) | Return true if this set contains all elements of another set.    |
+| Function                    | Description                                                      |
+| --------------------------- | ---------------------------------------------------------------- |
+| [`isdisjoint`](#isdisjoint) | Return true if sets have no elements in common.                  |
+| [`isempty`](#isempty)       | Return true if the set has no elements.                          |
+| [`issubset`](#issubset)     | Return true if all elements of this set are also in another set. |
+| [`issuperset`](#issuperset) | Return true if this set contains all elements of another set.    |
 
 **Query**:
 
-| Function           | Description                               |
-| ------------------ | ----------------------------------------- |
-| [`len()`](#fn-len) | Return the number of elements in the set. |
+| Function                | Description                               |
+| ----------------------- | ----------------------------------------- |
+| [`contains`](#contains) | Return true if the set contains `v`.      |
+| [`len`](#len)           | Return the number of elements in the set. |
 
 **Transform**:
 
-| Function                 | Description                             |
-| ------------------------ | --------------------------------------- |
-| [`map(fn)`](#fn-mapfn)   | Return a new set by mapping each value. |
-| [`values()`](#fn-values) | Return a list of all values in the set. |
-
-## Functions
+| Function            | Description                             |
+| ------------------- | --------------------------------------- |
+| [`map`](#map)       | Return a new set by mapping each value. |
+| [`values`](#values) | Return a list of all values in the set. |
 
 ### Mutation
 
-#### `add(v)` {#fn-addv}
+In-place operations that mutate the current set.
 
-Add an element to the set.
-
-::: code-group
+#### `add`
 
-```lua [example.lua]
-local s = Set({ "a" })
-s:add("b")
--- result: s contains "a", "b"
-```
+Add an element to the set.
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param v any
----@return T self
-function add(v) end
+```lua
+s = Set({ "a" }):add("b") --> s contains "a", "b"
 ```
 
-:::
-
-#### `clear()` {#fn-clear}
+#### `clear`
 
 Remove all elements from the set.
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-s:clear()
--- result: s is empty
+```lua
+s = Set({ "a", "b" }):clear() --> s is empty
 ```
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@return T self
-function clear() end
-```
-
-:::
-
-#### `difference_update(set)` {#fn-difference_updateset}
+#### `difference_update`
 
 Remove elements found in another set (in place).
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-s:difference_update(Set({ "b" }))
--- result: s contains "a"
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T self
-function difference_update(set) end
+```lua
+s = Set({ "a", "b" }):difference_update(Set({ "b" })) --> s contains "a"
 ```
 
-:::
-
-#### `discard(v)` {#fn-discardv}
+#### `discard`
 
 Remove an element if present, do nothing otherwise.
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-s:discard("b")
--- result: s contains "a"
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param v any
----@return T self
-function discard(v) end
+```lua
+s = Set({ "a", "b" }):discard("b") --> s contains "a"
 ```
 
-:::
-
-#### `intersection_update(set)` {#fn-intersection_updateset}
+#### `intersection_update`
 
 Keep only elements common to both sets (in place).
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-s:intersection_update(Set({ "b", "c" }))
--- result: s contains "b"
+```lua
+s = Set({ "a", "b" }):intersection_update(Set({ "b", "c" }))
+--> s contains "b"
 ```
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T self
-function intersection_update(set) end
-```
-
-:::
-
-#### `pop()` {#fn-pop}
+#### `pop`
 
 Remove and return an arbitrary element.
 
-::: code-group
-
-```lua [example.lua]
-local v = Set({ "a", "b" }):pop()
--- result: v is either "a" or "b"
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@return any
-function pop() end
+```lua
+v = Set({ "a", "b" }):pop() --> v is either "a" or "b"
 ```
 
-:::
-
-#### `symmetric_difference_update(set)` {#fn-symmetric_difference_updateset}
+#### `symmetric_difference_update`
 
 Update the set with elements not shared by both (in place).
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-s:symmetric_difference_update(Set({ "b", "c" }))
--- result: s contains "a", "c"
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T self
-function symmetric_difference_update(set) end
+```lua
+s = Set({ "a", "b" }):symmetric_difference_update(Set({ "b", "c" }))
+--> s contains "a", "c"
 ```
 
-:::
-
-#### `update(set)` {#fn-updateset}
+#### `update`
 
 Add all elements from another set (in place).
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a" })
-s:update(Set({ "b" }))
--- result: s contains "a", "b"
+```lua
+s = Set({ "a" }):update(Set({ "b" })) --> s contains "a", "b"
 ```
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T self
-function update(set) end
-```
-
-:::
-
 ### Copying
 
-#### `copy()` {#fn-copy}
+Non-mutating set operations that return new set instances.
 
-Return a shallow copy of the set.
-
-::: code-group
+#### `copy`
 
-```lua [example.lua]
-local s = Set({ "a" })
-local c = s:copy()
--- result: c is a new set with "a"
-```
+Return a shallow copy of the set.
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@return T set
----@nodiscard
-function copy() end
+```lua
+c = Set({ "a" }):copy() --> c is a new set with "a"
 ```
 
-:::
-
-### Set Operations
-
-#### `difference(set)` {#fn-differenceset}
+#### `difference`
 
 Return elements in this set but not in another.
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-local d = s:difference(Set({ "b" }))
--- result: d contains "a"
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T set
----@nodiscard
-function difference(set) end
+```lua
+d = Set({ "a", "b" }):difference(Set({ "b" })) --> d contains "a"
 ```
 
-:::
-
-#### `intersection(set)` {#fn-intersectionset}
+#### `intersection`
 
 Return elements common to both sets.
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-local i = s:intersection(Set({ "b", "c" }))
--- result: i contains "b"
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T set
----@nodiscard
-function intersection(set) end
+```lua
+i = Set({ "a", "b" }):intersection(Set({ "b", "c" })) --> i contains "b"
 ```
 
-:::
-
-#### `symmetric_difference(set)` {#fn-symmetric_differenceset}
+#### `symmetric_difference`
 
 Return elements not shared by both sets.
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a", "b" })
-local d = s:symmetric_difference(Set({ "b", "c" }))
--- result: d contains "a", "c"
+```lua
+d = Set({ "a", "b" }):symmetric_difference(Set({ "b", "c" }))
+--> d contains "a", "c"
 ```
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T set
----@nodiscard
-function symmetric_difference(set) end
-```
-
-:::
-
-#### `union(set)` {#fn-unionset}
+#### `union`
 
 Return a new set with all elements from both.
 
-::: code-group
-
-```lua [example.lua]
-local s = Set({ "a" }):union(Set({ "b" }))
--- result: s contains "a", "b"
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return T set
----@nodiscard
-function union(set) end
+```lua
+s = Set({ "a" }):union(Set({ "b" })) --> s contains "a", "b"
 ```
 
-:::
-
 ### Predicates
 
-#### `isdisjoint(set)` {#fn-isdisjointset}
-
-Return true if sets have no elements in common.
+Boolean checks about set relationships and emptiness.
 
-::: code-group
+#### `isdisjoint`
 
-```lua [example.lua]
-local ok = Set({ "a" }):isdisjoint(Set({ "b" }))
--- result: true
-```
+Return true if sets have no elements in common.
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return boolean
----@nodiscard
-function isdisjoint(set) end
+```lua
+ok = Set({ "a" }):isdisjoint(Set({ "b" })) --> true
 ```
 
-:::
-
-#### `isempty()` {#fn-isempty}
+#### `isempty`
 
 Return true if the set has no elements.
 
-::: code-group
-
-```lua [example.lua]
-local empty = Set({}):isempty()
--- result: true
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@return boolean
----@nodiscard
-function isempty() end
+```lua
+empty = Set({}):isempty() --> true
 ```
 
-:::
-
-#### `issubset(set)` {#fn-issubsetset}
+#### `issubset`
 
 Return true if all elements of this set are also in another set.
 
-::: code-group
-
-```lua [example.lua]
-local ok = Set({ "a" }):issubset(Set({ "a", "b" }))
--- result: true
-```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return boolean
----@nodiscard
-function issubset(set) end
+```lua
+ok = Set({ "a" }):issubset(Set({ "a", "b" })) --> true
 ```
 
-:::
-
-#### `issuperset(set)` {#fn-issupersetset}
+#### `issuperset`
 
 Return true if this set contains all elements of another set.
 
-::: code-group
-
-```lua [example.lua]
-local ok = Set({ "a", "b" }):issuperset(Set({ "a" }))
--- result: true
+```lua
+ok = Set({ "a", "b" }):issuperset(Set({ "a" })) --> true
 ```
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param set T
----@return boolean
----@nodiscard
-function issuperset(set) end
-```
-
-:::
-
 ### Query
 
-#### `len()` {#fn-len}
+Read-only queries for membership and size.
 
-Return the number of elements in the set.
+#### `contains`
 
-::: code-group
+Return true if the set contains `v`.
 
-```lua [example.lua]
-local n = Set({ "a", "b" }):len()
--- result: 2
+```lua
+ok = Set({ "a", "b" }):contains("a") --> true
+ok = Set({ "a", "b" }):contains("z") --> false
 ```
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@return integer
----@nodiscard
-function len() end
-```
+#### `len`
 
-:::
+Return the number of elements in the set.
 
-### Transform
+```lua
+n = Set({ "a", "b" }):len() --> 2
+```
 
-#### `map(fn)` {#fn-mapfn}
+### Transform
 
-Return a new set by mapping each value.
+Value-to-value transformations and projection helpers.
 
-::: code-group
+#### `map`
 
-```lua [example.lua]
-local s = Set({ 1, 2 }):map(function(v) return v * 10 end)
--- result: s contains 10, 20
-```
+Return a new set by mapping each value.
 
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@param fn fun(v:any):any
----@return T set
----@nodiscard
-function map(fn) end
+```lua
+s = Set({ 1, 2 }):map(function(v) return v * 10 end) --> s contains 10, 20
 ```
 
-:::
-
-#### `values()` {#fn-values}
+#### `values`
 
 Return a list of all values in the set.
 
-::: code-group
-
-```lua [example.lua]
-local values = Set({ "a", "b" }):values()
--- result: { "a", "b" }
+```lua
+values = Set({ "a", "b" }):values() --> { "a", "b" }
 ```
-
-```lua [signature.lua]
----@generic T:mods.Set|table<any,true>
----@param self T
----@return mods.List|any[] values
----@nodiscard
-function values() end
-```
-
-:::