From c416178fb23943c35e0f32f7447ab4c59b4f6a70 Mon Sep 17 00:00:00 2001
From: Ian Moffett <ian@osmora.org>
Date: Sun, 3 Aug 2025 16:59:04 -0400
Subject: docs: liboda: Add input management section

Signed-off-by: Ian Moffett <ian@osmora.org>
---
 share/docs/lib/liboda.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

(limited to 'share')

diff --git a/share/docs/lib/liboda.md b/share/docs/lib/liboda.md
index ee82dc0..e5345a4 100644
--- a/share/docs/lib/liboda.md
+++ b/share/docs/lib/liboda.md
@@ -189,3 +189,41 @@ structure to minimize the number of parameters used in the function signature.
 
 Upon failure of ``oda_reqwin()`` a negative POSIX errno value
 is returned (see ``sys/errno.h``).
+
+### Input management
+
+The liboda library additionally provides an input API that facilitates
+management of user input (e.g., keyboard).
+
+(See ``liboda/input.h``)
+
+#### The ``oda_key`` structure
+
+ODA provides a standard description of keys received from a keyboard
+device. Keyboard input is represented by the ``oda_key`` structure shown
+below:
+
+```c
+struct oda_key {
+    uint16_t type;
+    uint8_t scancode;
+    char ch;
+    ...
+};
+```
+
+The ``type`` field describes the key type, valid key types can be
+found within the ``ODA_KEY_*`` definitions in ``liboda/input.h``.
+
+The ``scancode`` field contains the raw keyboard scancode received
+from the device.
+
+The ``ch`` field contains the ASCII representation of the input received
+from the device.
+
+#### The ``oda_kbd`` structure
+
+ODA represents keyboard devices through the ``oda_kbd`` structure found
+in ``liboda/input.h``. This structure contains callbacks that are set up
+by the compositor to be invoked when their respective keyboard related
+event occurs.
-- 
cgit v1.2.3