chore(docs): auto-generate docs (#16)

github-actions[bot] · haithium · web-flow · commit d0b80d0b4c4f · 2026-03-06T09:54:48.000+02:00
* chore(docs): auto-generate docs

* Delete docs/src/modules/ntpath.md

* Delete docs/src/modules/path.md

* Delete docs/src/modules/posixpath.md

---------

Co-authored-by: haithium &lt;128622475+haithium@users.noreply.github.com&gt;
diff --git a/docs/src/modules/is.md b/docs/src/modules/is.md
@@ -1,10 +1,10 @@
 ---
-desc: "Type predicates for Lua values and filesystem path kinds."
+description: "Type predicates for Lua values and filesystem path types."
 ---
 
 # `is`
 
-Type predicates for Lua values and filesystem path kinds.
+Type predicates for Lua values and filesystem path types.
 
 ## Usage
 
@@ -65,16 +65,16 @@ is("hello", "STRING") --> true
 
 **Path Checks**:
 
-| Function                  | Description                                             |
-| ------------------------- | ------------------------------------------------------- |
-| [`block(v)`](#fn-block)   | Returns `true` when `v` is a block device path.         |
-| [`char(v)`](#fn-char)     | Returns `true` when `v` is a char device path.          |
-| [`device(v)`](#fn-device) | Returns `true` when `v` is a block or char device path. |
-| [`dir(v)`](#fn-dir)       | Returns `true` when `v` is a directory path.            |
-| [`fifo(v)`](#fn-fifo)     | Returns `true` when `v` is a FIFO path.                 |
-| [`file(v)`](#fn-file)     | Returns `true` when `v` is a file path.                 |
-| [`link(v)`](#fn-link)     | Returns `true` when `v` is a symlink path.              |
-| [`socket(v)`](#fn-socket) | Returns `true` when `v` is a socket path.               |
+| Function                  | Description                                                  |
+| ------------------------- | ------------------------------------------------------------ |
+| [`block(v)`](#fn-block)   | Returns `true` when `v` is a block device path.              |
+| [`char(v)`](#fn-char)     | Returns `true` when `v` is a character device path.          |
+| [`device(v)`](#fn-device) | Returns `true` when `v` is a block or character device path. |
+| [`dir(v)`](#fn-dir)       | Returns `true` when `v` is a directory path.                 |
+| [`fifo(v)`](#fn-fifo)     | Returns `true` when `v` is a FIFO path.                      |
+| [`file(v)`](#fn-file)     | Returns `true` when `v` is a file path.                      |
+| [`link(v)`](#fn-link)     | Returns `true` when `v` is a symlink path.                   |
+| [`socket(v)`](#fn-socket) | Returns `true` when `v` is a socket path.                    |
 
 ### Type Checks
 
@@ -362,13 +362,13 @@ is.truthy("non-empty")
 
 ### Path Checks
 
-Filesystem path kind checks.
+Filesystem path type checks.
 
 > [!IMPORTANT]
 >
 > Path checks require **LuaFileSystem**
-> ([`lfs`](https://github.com/lunarmodules/luafilesystem)) and raise an error it
-> is not installed. <a id="fn-block"></a>
+> ([`lfs`](https://github.com/lunarmodules/luafilesystem)) and raise an error if
+> it is not installed. <a id="fn-block"></a>
 
 #### `block(v)`
 
@@ -392,7 +392,7 @@ is.block("/dev/sda")
 
 #### `char(v)`
 
-Returns `true` when `v` is a char device path.
+Returns `true` when `v` is a character device path.
 
 **Parameters**:
 
@@ -412,7 +412,7 @@ is.char("/dev/null")
 
 #### `device(v)`
 
-Returns `true` when `v` is a block or char device path.
+Returns `true` when `v` is a block or character device path.
 
 **Parameters**:
 
diff --git a/docs/src/modules/keyword.md b/docs/src/modules/keyword.md
@@ -1,5 +1,5 @@
 ---
-desc: "Lua keyword helpers."
+description: "Lua keyword helpers."
 ---
 
 # `keyword`
@@ -17,13 +17,13 @@ kw.isidentifier("hello_world") --> true
 
 ## Functions
 
-| Function                                              | Description                                                                         |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| [`iskeyword(v)`](#fn-iskeyword)                       | Return `true` when `v` is a reserved Lua keyword.                                   |
-| [`isidentifier(v)`](#fn-isidentifier)                 | Return `true` when `v` is a valid non-keyword Lua identifier.                       |
-| [`kwlist()`](#fn-kwlist)                              | Return Lua keywords as a [`mods.List`](https://luamod.github.io/mods/modules/list). |
-| [`kwset()`](#fn-kwset)                                | Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set).   |
-| [`normalize_identifier(s)`](#fn-normalize-identifier) | Normalize an input into a safe Lua identifier.                                      |
+| Function                                              | Description                                                   |
+| ----------------------------------------------------- | ------------------------------------------------------------- |
+| [`iskeyword(v)`](#fn-iskeyword)                       | Return `true` when `v` is a reserved Lua keyword.             |
+| [`isidentifier(v)`](#fn-isidentifier)                 | Return `true` when `v` is a valid non-keyword Lua identifier. |
+| [`kwlist()`](#fn-kwlist)                              | Return Lua keywords as a [`mods.List`](/modules/list).        |
+| [`kwset()`](#fn-kwset)                                | Return Lua keywords as a [`mods.Set`](/modules/set).          |
+| [`normalize_identifier(s)`](#fn-normalize-identifier) | Normalize an input into a safe Lua identifier.                |
 
 <a id="fn-iskeyword"></a>
 
@@ -71,8 +71,7 @@ kw.isidentifier("local") --> false
 
 ### `kwlist()`
 
-Return Lua keywords as a
-[`mods.List`](https://luamod.github.io/mods/modules/list).
+Return Lua keywords as a [`mods.List`](/modules/list).
 
 **Return**:
 
@@ -88,8 +87,7 @@ kw.kwlist():contains("and") --> true
 
 ### `kwset()`
 
-Return Lua keywords as a
-[`mods.Set`](https://luamod.github.io/mods/modules/set).
+Return Lua keywords as a [`mods.Set`](/modules/set).
 
 **Return**:
 
diff --git a/docs/src/modules/list.md b/docs/src/modules/list.md
@@ -1,5 +1,5 @@
 ---
-desc:
+description:
   "A list class providing common operations to create, modify, and query
   sequences of values."
 ---
diff --git a/docs/src/modules/operator.md b/docs/src/modules/operator.md
@@ -1,5 +1,5 @@
 ---
-desc: "Operator helpers as functions."
+description: "Operator helpers as functions."
 ---
 
 # `operator`
diff --git a/docs/src/modules/repr.md b/docs/src/modules/repr.md
@@ -1,5 +1,5 @@
 ---
-desc: "Render any Lua value as a readable string."
+description: "Render any Lua value as a readable string."
 ---
 
 # `repr`
diff --git a/docs/src/modules/runtime.md b/docs/src/modules/runtime.md
@@ -1,5 +1,5 @@
 ---
-desc: "Exposes Lua runtime metadata and version compatibility flags."
+description: "Exposes Lua runtime metadata and version compatibility flags."
 ---
 
 # `runtime`
@@ -25,6 +25,7 @@ print(runtime.is_lua54)    --> true | false
 | [`minor`](#minor)             | Minor version number parsed from `version`.       |
 | [`version_num`](#version-num) | Numeric version encoded as `major * 100 + minor`. |
 | [`is_luajit`](#is-luajit)     | True when running under LuaJIT.                   |
+| [`is_windows`](#is-windows)   | True when running on a Windows host.              |
 | [`is_lua51`](#is-lua51)       | True only on Lua 5.1 runtimes.                    |
 | [`is_lua52`](#is-lua52)       | True only on Lua 5.2 runtimes.                    |
 | [`is_lua53`](#is-lua53)       | True only on Lua 5.3 runtimes.                    |
@@ -70,6 +71,14 @@ True when running under LuaJIT.
 print(runtime.is_luajit) --> true | false
 ```
 
+### `is_windows`
+
+True when running on a Windows host.
+
+```lua
+print(runtime.is_windows) --> true | false
+```
+
 ### `is_lua51`
 
 True only on Lua 5.1 runtimes.
diff --git a/docs/src/modules/set.md b/docs/src/modules/set.md
@@ -1,5 +1,5 @@
 ---
-desc:
+description:
   "A set class providing common operations to create, modify, and query
   collections of unique values."
 ---
diff --git a/docs/src/modules/str.md b/docs/src/modules/str.md
@@ -1,5 +1,5 @@
 ---
-desc: "String utility helpers modeled after Python's `str`."
+description: "String utility helpers modeled after Python's `str`."
 ---
 
 # `str`
@@ -247,8 +247,7 @@ s = format_map("hi {name}", { name = "bob" }) --> "hi bob"
 > [!NOTE]
 >
 > `format_map` is a lightweight `{key}` replacement helper. For richer
-> templating, use
-> [`mods.template`](https://luamod.github.io/mods/modules/template).
+> templating, use [`mods.template`](/modules/template).
 
 ### Predicates
 
diff --git a/docs/src/modules/stringcase.md b/docs/src/modules/stringcase.md
@@ -1,5 +1,5 @@
 ---
-desc: "String case conversion helpers."
+description: "String case conversion helpers."
 ---
 
 # `stringcase`
diff --git a/docs/src/modules/tbl.md b/docs/src/modules/tbl.md
@@ -1,5 +1,5 @@
 ---
-desc: "Utility functions for working with Lua tables."
+description: "Utility functions for working with Lua tables."
 ---
 
 # `tbl`
@@ -39,7 +39,6 @@ print(tbl.count({ a = 1, b = 2 })) --> 2
 | [`same(a, b)`](#fn-same)          | Return `true` if two tables have the same keys and equal values. |
 | [`find_if(t, pred)`](#fn-find-if) | Find first value and key matching predicate.                     |
 | [`get(t, ...)`](#fn-get)          | Safely get nested value by keys.                                 |
-| [`keypath(...)`](#fn-keypath)     | Format a key chain as a Lua-like table access path.              |
 
 **Transforms**:
 
@@ -263,29 +262,6 @@ v2 = get(t)                --> { a = { b = { c = 1 } } }
 >
 > If no keys are provided, returns the input table.
 
-<a id="fn-keypath"></a>
-
-#### `keypath(...)`
-
-Format a key chain as a Lua-like table access path.
-
-**Parameters**:
-
-- `...` (`any`): Additional arguments.
-
-**Return**:
-
-- `path` (`string`): Rendered key path.
-
-**Example**:
-
-```lua
-p1 = keypath("t", "a", "b", "c")        --> "t.a.b.c"
-p2 = keypath("ctx", "users", 1, "name") --> "ctx.users[1].name"
-p3 = keypath("ctx", "invalid-key")      --> 'ctx["invalid-key"]'
-p4 = keypath()                          --> ""
-```
-
 ### Transforms
 
 Table transformation and conversion utilities. <a id="fn-invert"></a>
diff --git a/docs/src/modules/template.md b/docs/src/modules/template.md
@@ -1,5 +1,5 @@
 ---
-desc: "Interpolate string placeholders of the form <code v-pre>{{."
+description: "Interpolate string placeholders of the form <code v-pre>{{."
 ---
 
 # `template`
@@ -85,8 +85,7 @@ template("Hi {{name_func}}", view) --> "Hi Ada"
 
 ## Table Values
 
-Table placeholders are rendered using
-[`mods.repr`](https://luamod.github.io/mods/modules/repr).
+Table placeholders are rendered using `mods.repr`.
 
 ```lua
 view = { data = { a = 1, b = true } }
diff --git a/docs/src/modules/utils.md b/docs/src/modules/utils.md
@@ -1,5 +1,5 @@
 ---
-desc: "Small shared utility helpers used by modules in this library."
+description: "Small shared utility helpers used by modules in this library."
 ---
 
 # `utils`
@@ -24,11 +24,11 @@ Smart-quote a string for readable Lua-like output.
 
 **Parameters**:
 
-- `v` (`string`)
+- `v` (`string`): String to quote.
 
 **Return**:
 
-- `out` (`string`)
+- `out` (`string`): Quoted string.
 
 **Example**:
 
@@ -37,30 +37,60 @@ print(utils.quote('He said "hi"')) -- 'He said "hi"'
 print(utils.quote('say "hi" and \\'bye\\'')) -- "say \"hi\" and 'bye'"
 ```
 
-<a id="fn-repr"></a>
+<a id="fn-keypath"></a>
 
-### `repr(v)`
+### `keypath(...)`
 
-Render any Lua value as a string.
+Format a key chain as a Lua-like table access path.
 
-> [!NOTE]
->
-> Uses [`inspect`](https://github.com/kikito/inspect.lua) when available,
-> otherwise falls back to
-> [`mods.repr`](https://luamod.github.io/mods/modules/repr).
+**Parameters**:
+
+- `...` (`any`): Additional arguments.
+
+**Return**:
+
+- `path` (`string`): Rendered key path.
+
+**Example**:
+
+```lua
+p1 = utils.keypath("t", "a", "b", "c")        --> "t.a.b.c"
+p2 = utils.keypath("ctx", "users", 1, "name") --> "ctx.users[1].name"
+p3 = utils.keypath("ctx", "invalid-key")      --> 'ctx["invalid-key"]'
+p4 = utils.keypath()                          --> ""
+```
+
+<a id="fn-assert-arg"></a>
+
+### `assert_arg(argn, v, tp?, level?, msg?)`
+
+Assert argument value using [`mods.validate`](/modules/validate) and raise a Lua
+error on failure.
 
 **Parameters**:
 
-- `v` (`any`)
+- `argn` (`integer`): Argument index for error context.
+- `v` (`T`): Value to check.
+- `tp?` (`modsIsType`): Validator name (defaults to `"truthy"`).
+- `level?` (`integer`): Optional error level for `error(...)` (defaults to `2`).
+- `msg?` (`string`): Optional override template passed to
+  [`mods.validate`](/modules/validate).
 
 **Return**:
 
-- `out` (`string`)
+- `v` (`T`): Same input value on success.
 
 **Example**:
 
 ```lua
-print(utils.repr({ a = 1 })) --> {
---                                 a = 1
---                               }
+utils.assert_arg(1, "ok", "string") --> "ok"
+utils.assert_arg(2, 123, "string")
+--> raises: bad argument #2 (expected string, got number)
+utils.assert_arg(3, "x", "number", 2, "need {{expected}}, got {{got}}")
+--> raises: bad argument #3 (need number, got string)
 ```
+
+> [!NOTE]
+>
+> When the caller function name is available, error text includes
+> `to '<function>'` (Lua-style bad argument context).
diff --git a/docs/src/modules/validate.md b/docs/src/modules/validate.md
@@ -1,5 +1,5 @@
 ---
-desc: "Validation checks for values and filesystem path types."
+description: "Validation checks for values and filesystem path types."
 ---
 
 # `validate`
@@ -667,8 +667,8 @@ ok, err = validate.number("x") --> false, "need number, got string"
 > validate.messages.truthy = "expected {{expected}} value, got {{value}}"
 > validate.truthy(nil) --> false, "expected truthy value, got no value"
 > ```
->
-> **Default Messages**:
+
+**Default Messages**:
 
 - Type checks: <code v-pre>expected {{expected}}, got {{got}}</code>
 - Value checks: <code v-pre>expected {{expected}} value, got {{value}}</code>
