From 0629f3c79ca7abeefd07bb73ab858c795c85107d Mon Sep 17 00:00:00 2001 From: haithium <128622475+haithium@users.noreply.github.com> Date: Mon, 15 Jun 2026 18:41:42 +0000 Subject: [PATCH] docs: generate docs --- docs/api/device.md | 21 +++++--- docs/api/devices.md | 17 +++++-- docs/api/events.md | 20 +++++--- docs/api/selector.md | 67 +++++++++++++------------ docs/api/uinput.md | 27 +++++++--- docs/types.md | 114 +++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 211 insertions(+), 55 deletions(-) create mode 100644 docs/types.md diff --git a/docs/api/device.md b/docs/api/device.md index 10a3b64..3fd824b 100644 --- a/docs/api/device.md +++ b/docs/api/device.md @@ -15,7 +15,7 @@ One Linux input event returned by `Device:read()`. | [`flush()`](#fn-flush) | Drain queued events and return how many were discarded. | | [`get_repeat()`](#fn-get-repeat) | Return the current auto-repeat delay and period in milliseconds. | | [`grab()`](#fn-grab) | Take exclusive control of the input device. | -| [`is_device(value)`](#fn-is-device) | Return whether a value is an `evdev.Device` instance. | +| [`is_device(value)`](#fn-is-device) | Return whether a value is an [`evdev.Device`] instance. | | [`is_open()`](#fn-is-open) | Return whether this device handle still has an open file descriptor. | | [`open(path)`](#fn-open) | Open an input device by path. | | [`poll()`](#fn-poll) | Wait in the kernel until this device has input available. | @@ -76,7 +76,7 @@ Return the underlying Linux file descriptor. **Return**: -- `fd` (`evdev.fd?`): Linux file descriptor. +- `fd` ([`evdev.fd`]`?`): Linux file descriptor. **Example**: @@ -161,7 +161,7 @@ assert(dev:grab()) ### `is_device(value)` -Return whether a value is an `evdev.Device` instance. +Return whether a value is an [`evdev.Device`] instance. **Parameters**: @@ -211,11 +211,11 @@ Open an input device by path. **Parameters**: -- `path` (`evdev.path`) +- `path` ([`evdev.path`]) **Return**: -- `dev` (`evdev.Device?`): Open input device. +- `dev` ([`evdev.Device`]`?`): Open input device. - `err` (`string?`): Error message on failure. **Example**: @@ -266,7 +266,7 @@ Read one input event. Returns `nil` when no event is queued. **Return**: -- `event` (`evdev.event?`): Next queued input event. +- `event` ([`evdev.event`]`?`): Next queued input event. - `err` (`string?`): Error message on failure. **Example**: @@ -335,3 +335,12 @@ local dev = assert(Device("/dev/input/eventX")) assert(dev:grab()) assert(dev:ungrab()) ``` + + + +[`evdev.Device`]: /evdev/api/device.html +[`evdev.event`]: /evdev/types.html#evdev-event +[`evdev.fd`]: /evdev/types.html#evdev-fd +[`evdev.path`]: /evdev/types.html#evdev-path + + diff --git a/docs/api/devices.md b/docs/api/devices.md index 2fbff40..465bcc8 100644 --- a/docs/api/devices.md +++ b/docs/api/devices.md @@ -27,11 +27,11 @@ Read metadata for one input device by path. **Parameters**: -- `path` (`evdev.path`) +- `path` ([`evdev.path`]) **Return**: -- `info` (`evdev.deviceInfo?`) +- `info` ([`evdev.deviceInfo`]`?`) - `err` (`string?`) **Example**: @@ -54,7 +54,7 @@ Return the first discovered input device matching a path or a device name. **Return**: -- `dev` (`evdev.deviceInfo?`) +- `dev` ([`evdev.deviceInfo`]`?`) - `err` (`string?`) **Example**: @@ -86,7 +86,7 @@ Return all discovered input devices matching a path, alias, or device name. **Return**: -- `devs` (`evdev.deviceInfo[]?`) +- `devs` ([`evdev.deviceInfo`]`[]?`) - `err` (`string?`) **Example**: @@ -113,7 +113,7 @@ List evdev input devices under `/dev/input`. **Return**: -- `devs` (`evdev.deviceInfo[]?`) +- `devs` ([`evdev.deviceInfo`]`[]?`) - `err` (`string?`) **Example**: @@ -124,3 +124,10 @@ for _, dev in ipairs(devs) do print(dev.path, dev.name) end ``` + + + +[`evdev.deviceInfo`]: /evdev/types.html#evdev-deviceinfo +[`evdev.path`]: /evdev/types.html#evdev-path + + diff --git a/docs/api/events.md b/docs/api/events.md index 19c3dc4..c35c940 100644 --- a/docs/api/events.md +++ b/docs/api/events.md @@ -36,7 +36,7 @@ Return whether an event has type `EV_ABS`. **Parameters**: -- `event` (`evdev.event`) +- `event` ([`evdev.event`]) **Return**: @@ -57,7 +57,7 @@ Return whether an event has type `EV_KEY`. **Parameters**: -- `event` (`evdev.event`) +- `event` ([`evdev.event`]) **Return**: @@ -78,7 +78,7 @@ Return whether an event is a key/button press. **Parameters**: -- `event` (`evdev.event`) +- `event` ([`evdev.event`]) **Return**: @@ -99,7 +99,7 @@ Return whether an event has type `EV_REL`. **Parameters**: -- `event` (`evdev.event`) +- `event` ([`evdev.event`]) **Return**: @@ -120,7 +120,7 @@ Return whether an event is a key/button release. **Parameters**: -- `event` (`evdev.event`) +- `event` ([`evdev.event`]) **Return**: @@ -141,7 +141,7 @@ Return whether an event is a key repeat. **Parameters**: -- `event` (`evdev.event`) +- `event` ([`evdev.event`]) **Return**: @@ -162,7 +162,7 @@ Return whether an event has type `EV_SYN`. **Parameters**: -- `event` (`evdev.event`) +- `event` ([`evdev.event`]) **Return**: @@ -174,3 +174,9 @@ Return whether an event has type `EV_SYN`. local e = { type = evdev.ecodes.EV_SYN } print(evdev.events.is_syn(e)) --> true ``` + + + +[`evdev.event`]: /evdev/types.html#evdev-event + + diff --git a/docs/api/selector.md b/docs/api/selector.md index ec5a8bc..799a2b7 100644 --- a/docs/api/selector.md +++ b/docs/api/selector.md @@ -9,13 +9,39 @@ Selector for polling and reading from multiple devices. | Function | Description | | ------------------------------ | -------------------------------------------------------------- | +| [`new(devices?)`](#fn-new) | Create a selector from an optional list of devices. | | [`add(device)`](#fn-add) | Add a device to this selector. | | [`clear()`](#fn-clear) | Remove all devices from this selector. | | [`events()`](#fn-events) | Return an iterator that yields events from registered devices. | -| [`new(devices?)`](#fn-new) | Create a selector from an optional list of devices. | | [`poll()`](#fn-poll) | Wait until at least one registered device has input available. | | [`remove(device)`](#fn-remove) | Remove a device from this selector. | + + +### `new(devices?)` + +Create a selector from an optional list of devices. + +**Parameters**: + +- `devices?` ([`evdev.Device`]`[]`) + +**Return**: + +- **value** ([`evdev.Selector`]) + +**Example**: + +```lua +local evdev = require "evdev" +local Device = evdev.device.open +local Selector = evdev.selector.new + +local kb1 = assert(Device("/dev/input/event5")) +local kb2 = assert(Device("/dev/input/event10")) +local sel = Selector({ kb1, kb2 }) +``` + ### `add(device)` @@ -24,7 +50,7 @@ Add a device to this selector. **Parameters**: -- `device` (`evdev.Device`) +- `device` ([`evdev.Device`]) **Return**: @@ -91,32 +117,6 @@ for dev, e in sel:events() do end ``` - - -### `new(devices?)` - -Create a selector from an optional list of devices. - -**Parameters**: - -- `devices?` (`evdev.Device[]`) - -**Return**: - -- **value** (`evdev.Selector`) - -**Example**: - -```lua -local evdev = require "evdev" -local Device = evdev.device.open -local Selector = evdev.selector.new - -local kb1 = assert(Device("/dev/input/event5")) -local kb2 = assert(Device("/dev/input/event10")) -local sel = Selector({ kb1, kb2 }) -``` - ### `poll()` @@ -125,7 +125,7 @@ Wait until at least one registered device has input available. **Return**: -- `devs` (`evdev.Device[]?`) +- `devs` ([`evdev.Device`]`[]?`) - `err` (`string?`) **Example**: @@ -151,7 +151,7 @@ Remove a device from this selector. **Parameters**: -- `device` (`evdev.Device`) +- `device` ([`evdev.Device`]) **Return**: @@ -169,3 +169,10 @@ local sel = Selector({ kb1, kb2 }) sel:remove(kb2) ``` + + + +[`evdev.Device`]: /evdev/api/device.html +[`evdev.Selector`]: /evdev/api/selector.html + + diff --git a/docs/api/uinput.md b/docs/api/uinput.md index 537aa13..a7dd983 100644 --- a/docs/api/uinput.md +++ b/docs/api/uinput.md @@ -45,11 +45,11 @@ Create a virtual input device. **Parameters**: -- `spec?` (`evdev.uinputSpec`): Virtual device configuration. +- `spec?` ([`evdev.uinputSpec`]): Virtual device configuration. **Return**: -- `dev` (`evdev.UInput?`): Open virtual device. +- `dev` ([`evdev.UInput`]`?`): Open virtual device. - `err` (`string?`): Error message on failure. **Example**: @@ -73,10 +73,10 @@ Emit one raw input event. **Parameters**: -- `type` (`evdev.ecodes.ev`): Event type to emit. -- `code` (`evdev.ecodes.key|evdev.ecodes.btn|evdev.ecodes.rel`): Event code - within the selected type. -- `value` (`evdev.eventValue`): Event value to send. +- `type` ([`evdev.ecodes.ev`]): Event type to emit. +- `code` ([`evdev.ecodes.key`] | [`evdev.ecodes.btn`] | [`evdev.ecodes.rel`]): + Event code within the selected type. +- `value` ([`evdev.eventValue`]): Event value to send. **Return**: @@ -108,7 +108,7 @@ Get the file descriptor of the virtual device. **Return**: -- `fd` (`evdev.fd?`): Linux file descriptor. +- `fd` ([`evdev.fd`]`?`): Linux file descriptor. **Example**: @@ -210,3 +210,16 @@ local ui = assert(UInput()) ui:emit(evdev.ecodes.EV_KEY, evdev.ecodes.KEY_LEFTSHIFT, 0) ui:sync() ``` + + + +[`evdev.UInput`]: /evdev/api/uinput.html +[`evdev.ecodes.btn`]: /evdev/api/ecodes.html +[`evdev.ecodes.ev`]: /evdev/api/ecodes.html +[`evdev.ecodes.key`]: /evdev/api/ecodes.html +[`evdev.ecodes.rel`]: /evdev/api/ecodes.html +[`evdev.eventValue`]: /evdev/types.html#evdev-eventvalue +[`evdev.fd`]: /evdev/types.html#evdev-fd +[`evdev.uinputSpec`]: /evdev/types.html#evdev-uinputspec + + diff --git a/docs/types.md b/docs/types.md new file mode 100644 index 0000000..2a78072 --- /dev/null +++ b/docs/types.md @@ -0,0 +1,114 @@ +--- +title: "Types" +description: "Type aliases defined in the evdev module." +--- + +Type aliases defined in the evdev module. + +## [`evdev.coreDevice`] + +Open and manage input devices. + +| Field | Type | Optional | +| ------------ | ----------------------------------------------------------------------------------- | -------- | +| `close` | `fun(self): (ok:true?, err:string?)` | No | +| `fd` | `fun(self): (fd:`[`evdev.fd`](/evdev/types.html#evdev-fd)`?, err:string?)` | No | +| `flush` | `fun(self): (count:integer?, err:string?)` | No | +| `get_repeat` | `fun(self): (delay:integer?, period:integer?, err:string?)` | No | +| `grab` | `fun(self): (ok:true?, err:string?)` | No | +| `is_open` | `fun(self): boolean` | No | +| `poll` | `fun(self): (ready:boolean?, err:string?)` | No | +| `read` | `fun(self): (event:`[`evdev.event`](/evdev/types.html#evdev-event)`?, err:string?)` | No | +| `set_repeat` | `fun(self, delay:integer, period:integer): (ok:true?, err:string?)` | No | +| `ungrab` | `fun(self): (ok:true?, err:string?)` | No | + +## [`evdev.coreUInput`] + +Open virtual input device handle. + +| Field | Type | Optional | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| `close` | `fun(self): (ok:true?, err:string?)` | No | +| `emit` | `fun(self, type:`[`evdev.ecodes.ev`](/evdev/api/ecodes.html)`, code:integer, value:`[`evdev.eventValue`](/evdev/types.html#evdev-eventvalue)`): (ok:true?, err:string?)` | No | +| `get_repeat` | `fun(self): (delay:integer?, period_or_err:(integer` \| `string)?)` | No | +| `info` | `fun(self): (info:`[`evdev.deviceInfo`](/evdev/types.html#evdev-deviceinfo)`?, err:string?)` | No | +| `is_open` | `fun(self): boolean` | No | +| `set_repeat` | `fun(self, delay:integer, period:integer): (ok:true?, err:string?)` | No | +| `sync` | `fun(self): (ok:true?, err:string?)` | No | + +## [`evdev.deviceInfo`] + +Input device metadata. + +| Field | Type | Optional | Description | +| -------------- | ---------- | -------- | ----------------------------------------------------------- | +| `bustype` | `integer` | No | Bus type from the kernel input ID. | +| `id_aliases` | `string[]` | Yes | Symlink aliases under `/dev/input/by-id`, when available. | +| `name` | `string` | Yes | Device name reported by the kernel. | +| `path` | `string` | No | Device node path. | +| `path_aliases` | `string[]` | Yes | Symlink aliases under `/dev/input/by-path`, when available. | +| `phys` | `string` | Yes | Physical device path, when available. | +| `product` | `integer` | No | Product ID from the kernel input ID. | +| `uniq` | `string` | Yes | Unique identifier string, when available. | +| `vendor` | `integer` | No | Vendor ID from the kernel input ID. | +| `version` | `integer` | No | Hardware version from the kernel input ID. | + +## [`evdev.event`] + +One Linux input event returned by `Device:read()`. + +| Field | Type | Optional | +| -------- | -------------------------------------------------------- | -------- | +| `code` | `integer` | No | +| `device` | [`evdev.Device`](/evdev/api/device.html) | Yes | +| `sec` | `integer` | Yes | +| `type` | [`evdev.ecodes.ev`](/evdev/api/ecodes.html) | No | +| `usec` | `integer` | Yes | +| `value` | [`evdev.eventValue`](/evdev/types.html#evdev-eventvalue) | No | + +## [`evdev.eventValue`] + +Numeric value attached to an input event. + +`integer` + +## [`evdev.fd`] + +Linux file descriptor number. + +`integer` + +## [`evdev.path`] + +Path to an evdev device node or related input path. + +`string` + +## [`evdev.uinputSpec`] + +Configuration used to create a `/dev/uinput` virtual device. + +| Field | Type | Optional | Description | +| ------------- | ---------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------- | +| `bustype` | `integer` | Yes | Linux bus type (default: `BUS_USB` / 3). | +| `event_types` | [`evdev.ecodes.ev`](/evdev/api/ecodes.html)`[]` | Yes | Event types to enable. Defaults to `EV_SYN`, plus `EV_KEY`/`EV_REP` for keyboard keys and `EV_REL` for relative axes. | +| `keys` | `(`[`evdev.ecodes.key`](/evdev/api/ecodes.html) \| [`evdev.ecodes.btn`](/evdev/api/ecodes.html)`)[]` | Yes | Keys/buttons to expose. Defaults to all real `KEY_*` and `BTN_*` codes when omitted. | +| `name` | `string` | Yes | Device name shown by the kernel (default: `"Lua evdev virtual keyboard"`). | +| `path` | `string` | Yes | uinput control node (default: `"/dev/uinput"`). Kernel assigns `/dev/input/eventX`. | +| `product` | `integer` | Yes | Product ID (default: `0xE7DE`). | +| `rels` | [`evdev.ecodes.rel`](/evdev/api/ecodes.html)`[]` | Yes | Relative axes to expose. Defaults to all real `REL_*` codes when omitted. | +| `vendor` | `integer` | Yes | Vendor ID (default: `0x1209`). | +| `version` | `integer` | Yes | Version number (default: `1`). | + + + +[`evdev.coreDevice`]: https://github.com/BlueLua/evdev/blob/main/types/device.d.lua#L29-L43 +[`evdev.coreUInput`]: https://github.com/BlueLua/evdev/blob/main/types/uinput.d.lua#L63-L74 +[`evdev.deviceInfo`]: https://github.com/BlueLua/evdev/blob/main/types/device.d.lua#L14-L28 +[`evdev.eventValue`]: https://github.com/BlueLua/evdev/blob/main/types/evdev.d.lua#L3-L6 +[`evdev.event`]: https://github.com/BlueLua/evdev/blob/main/types/device.d.lua#L3-L13 +[`evdev.fd`]: https://github.com/BlueLua/evdev/blob/main/types/evdev.d.lua#L3-L6 +[`evdev.path`]: https://github.com/BlueLua/evdev/blob/main/types/evdev.d.lua#L3-L6 +[`evdev.uinputSpec`]: https://github.com/BlueLua/evdev/blob/main/types/uinput.d.lua#L3-L16 + +