better public interface and doxygen

1 files changed, 40 insertions, 0 deletions

diff --git a/docs/migrating.md b/docs/migrating.md
new file mode 100644
index 0000000..d224cd4
--- /dev/null
+++ b/docs/migrating.md
@@ -0,0 +1,40 @@
+# Migrating pre-release applications
+
+YASL 0.1 has no stable source or binary compatibility promise. Rebuild all
+consumers against the matching installed headers and library after updating.
+The following changes replace backend-specific input fields with a common
+contract. See the [application guide](guide.md) for the full input workflow.
+
+## Keyboard events
+
+| Previous use | Replacement |
+| --- | --- |
+| Linux keysym or Cocoa virtual keycode in `key.key` | Portable physical `YASL_KEY_*` identity |
+| `key.base` | `key.native_code`, with explicit backend-specific encoding |
+| `key.keypad` | Distinct `YASL_KEY_KP_*` identities |
+| Advisory `key.text` character | `YASL_INPUT_TEXT` UTF-8 payload for insertion |
+| Layout label from a keysym | Optional `key.codepoint` and `key.shifted` Unicode scalars |
+
+Replace magic numbers and X11 symbols with named keys. For example, a quit
+command checks `key.key == YASL_KEY_ESCAPE` on a press. `YASL_KEY_A` means the
+US A position on every layout; use layout labels when a command should follow
+the printed letter instead. Do not cast key identities to characters. Keypad
+Enter and ordinary Enter now have distinct identities without a separate flag.
+
+Text comes only from `YASL_INPUT_TEXT`. Handle its byte length, copy it when
+retaining it after the next successful poll, and allow multiple characters per
+commit. Cocoa sends key events through its text input manager; Wayland emits
+ordinary XKB text and locale compose results in addition to IME commits.
+
+## Scroll events
+
+Replace `scroll_lines`, `scroll_delta`, and scroll button numbers with
+`mouse.scroll.x` and `.y` when `mouse.kind == YASL_PTR_SCROLL`. These double
+values are fractional line offsets, positive right/down on every backend.
+Do not infer scroll direction from `button`. One event may include both axes.
+Remove backend-specific sign inversions and whole-line casts; multiply the
+offset by your application's preferred pixels per line instead.
+
+X11 still supplies whole wheel steps. Wayland high-resolution wheels and smooth
+offsets, and Cocoa precise scrolling, preserve fractions. Device acceleration
+and system preferences still affect the native offsets.