Add some initial documentation for events

Credit to @BradyFromDiscord for writing these. See #640 and #565.

Co-authored-by: Brady <bradyakent@gmail.com

doc/events/char.md

@@ -0,0 +1,24 @@
+---
+module: [kind=event] char
+see: key To listen to any key press.
+---
+
+The @{char} event is fired when a character is _typed_ on the keyboard.
+
+The @{char} event is different to a key press. Sometimes multiple key presses may result in one character being
+typed (for instance, on some European keyboards). Similarly, some keys (e.g. <kbd>Ctrl</kbd>) do not have any
+corresponding character. The @{key} should be used if you want to listen to key presses themselves.
+
+## Return values
+1. @{string}: The event name.
+2. @{string}: The string representing the character that was pressed.
+
+
+## Example
+Prints each character the user presses:
+```lua
+while true do
+  local event, character = os.pullEvent("char")
+  print(character .. " was pressed.")
+end
+```

doc/events/key.md

@@ -0,0 +1,26 @@
+---
+module: [kind=event] key
+---
+
+This event is fired when any key is pressed while the terminal is focused.
+
+This event returns a numerical "key code" (for instance, <kbd>F1</kbd> is 290). This value may vary between versions and
+so it is recommended to use the constants in the @{keys} API rather than hard coding numeric values.
+
+If the button pressed represented a printable character, then the @{key} event will be followed immediately by a @{char}
+event. If you are consuming text input, use a @{char} event instead!
+
+## Return values
+1. [`string`]: The event name.
+2. [`number`]: The numerical key value of the key pressed.
+3. [`boolean`]: Whether the key event was generated while holding the key (@{true}), rather than pressing it the first time (@{false}).
+
+## Example
+Prints each key when the user presses it, and if the key is being held.
+
+```lua
+while true do
+  local event, key, is_held = os.pullEvent("key")  
+  print(("%s held=%b"):format(keys.getName(key), is_held))
+end
+```

doc/events/key_up.md

@@ -0,0 +1,24 @@
+---
+module: [kind=event] key_up
+see: keys For a lookup table of the given keys.
+---
+
+Fired whenever a key is released (or the terminal is closed while a key was being pressed).
+
+This event returns a numerical "key code" (for instance, <kbd>F1</kbd> is 290). This value may vary between versions and
+so it is recommended to use the constants in the @{keys} API rather than hard coding numeric values.
+
+## Return values
+1. @{string}: The event name.
+2. @{number}: The numerical key value of the key pressed.
+
+## Example
+Prints each key released on the keyboard whenever a @{key_up} event is fired.
+
+```lua
+while true do
+  local event, key = os.pullEvent("key_up")
+  local name = keys.getName(key) or "unknown key"
+  print(name .. " was released.")
+end
+```

doc/events/mouse_click.md

@@ -0,0 +1,34 @@
+---
+module: [kind=event] mouse_click
+---
+
+This event is fired when the terminal is clicked with a mouse. This event is only fired on advanced computers (including
+advanced turtles and pocket computers).
+
+## Return values
+1. @{string}: The event name.
+2. @{number}: The mouse button that was clicked.
+3. @{number}: The X-coordinate of the click.
+4. @{number}: The Y-coordinate of the click.
+
+## Mouse buttons
+Several mouse events (@{mouse_click}, @{mouse_up}, @{mouse_scroll}) contain a "mouse button" code. This takes a
+numerical value depending on which button on your mouse was last pressed when this event occurred.
+
+<table class="pretty-table">
+    <!-- Our markdown parser doesn't work on tables!? Guess I'll have to roll my own soonish :/. -->
+    <tr><th>Button code</th><th>Mouse button</th></tr>
+    <tr><td align="right">1</td><td>Left button</td></tr>
+    <tr><td align="right">2</td><td>Middle button</td></tr>
+    <tr><td align="right">3</td><td>Right button</td></tr>
+</table>
+
+## Example
+Print the button and the coordinates whenever the mouse is clicked.
+
+```lua
+while true do
+  local event, button, x, y = os.pullEvent("mouse_click")
+  print(("The mouse button %s was pressed at %d, %d"):format(button, x, y))
+end
+```

doc/events/mouse_drag.md

@@ -0,0 +1,24 @@
+---
+module: [kind=event] mouse_drag
+see: mouse_click For when a mouse button is initially pressed.
+---
+
+This event is fired every time the mouse is moved while a mouse button is being held.
+
+## Return values
+1. @{string}: The event name.
+2. @{number}: The [mouse button](mouse_click.html#Mouse_buttons) that is being pressed.
+3. @{number}: The X-coordinate of the mouse.
+4. @{number}: The Y-coordinate of the mouse.
+
+## Example
+Print the button and the coordinates whenever the mouse is dragged.
+
+```lua
+while true do
+  local event, button, x, y = os.pullEvent("mouse_drag")
+  print(("The mouse button %s was dragged at %d, %d"):format(button, x, y))
+end
+```
+
+

doc/events/mouse_scroll.md

@@ -0,0 +1,21 @@
+---
+module: [kind=event] mouse_scroll
+---
+
+This event is fired when a mouse wheel is scrolled in the terminal.
+
+## Return values
+1. @{string}: The event name.
+2. @{number}: The direction of the scroll. (-1 = up, 1 = down)
+3. @{number}: The X-coordinate of the mouse when scrolling.
+4. @{number}: The Y-coordinate of the mouse when scrolling.
+
+## Example
+Prints the direction of each scroll, and the position of the mouse at the time.
+
+```lua
+while true do
+  local event, dir, x, y = os.pullEvent("mouse_scroll")
+  print(("The mouse was scrolled in direction %s at %d, %d"):format(dir, x, y))
+end
+```

doc/events/mouse_up.md

@@ -0,0 +1,24 @@
+---
+module: [kind=event] mouse_up
+---
+
+This event is fired when a mouse button is released or a held mouse leaves the computer's terminal.
+
+## Return values
+1. @{string}: The event name.
+2. @{number}: The [mouse button](mouse_click.html#Mouse_buttons) that was released.
+3. @{number}: The X-coordinate of the mouse.
+4. @{number}: The Y-coordinate of the mouse.
+
+## Example
+Prints the coordinates and button number whenever the mouse is released.
+
+```lua
+while true do
+  local event, button, x, y = os.pullEvent("mouse_up")
+  print(("The mouse button %s was released at %d, %d"):format(button, x, y))
+end
+```
+
+[`string`]: string
+[`number`]: number

illuaminate.sexp

@@ -2,6 +2,7 @@
 
 (sources
   /doc/stub/
+  /doc/events/
   /build/docs/luaJavadoc/
   /src/main/resources/*/computercraft/lua/bios.lua
   /src/main/resources/*/computercraft/lua/rom/
@@ -25,7 +26,8 @@
 
   (module-kinds
     (peripheral Peripherals)
-    (generic_peripheral "Generic Peripherals"))
+    (generic_peripheral "Generic Peripherals")
+    (event Events))
 
   (library-path
     /doc/stub/