config: add documentation

jay-config/src/keyboard/mod.rs

@@ -1,13 +1,15 @@
+//! Tools affecting the keyboard behavior.
+
 use {
     crate::keyboard::{mods::Modifiers, syms::KeySym},
     bincode::{Decode, Encode},
     std::ops::{BitOr, BitOrAssign},
 };
 
-pub mod keymap;
 pub mod mods;
 pub mod syms;
 
+/// A keysym with zero or more modifiers
 #[derive(Encode, Decode, Copy, Clone, Eq, PartialEq, Hash, Debug)]
 pub struct ModifiedKeySym {
     pub mods: Modifiers,
@@ -39,3 +41,62 @@ impl BitOrAssign<Modifiers> for ModifiedKeySym {
         self.mods |= rhs;
     }
 }
+
+/// A keymap.
+#[derive(Encode, Decode, Copy, Clone, Debug, Eq, PartialEq, Hash)]
+pub struct Keymap(pub u64);
+
+impl Keymap {
+    /// The invalid keymap.
+    pub const INVALID: Self = Self(0);
+
+    /// Returns whether this keymap is valid.
+    pub fn is_valid(self) -> bool {
+        self != Self::INVALID
+    }
+
+    /// Returns whether this keymap is invalid.
+    pub fn is_invalid(self) -> bool {
+        self == Self::INVALID
+    }
+}
+
+/// Parses a keymap.
+///
+/// The returned keymap can later be used to set the keymap of a seat. If the keymap cannot
+/// be parsed, returns an invalid keymap. Trying to set a seat's keymap to an invalid keymap
+/// has no effect.
+///
+/// A simple keymap looks as follows:
+///
+/// ```text
+/// xkb_keymap {
+///     xkb_keycodes  { include "evdev+aliases(qwerty)" };
+///     xkb_types     { include "complete" };
+///     xkb_compat    { include "complete" };
+///     xkb_symbols   { include "pc+inet(evdev)+us(basic)" };
+/// };
+/// ```
+///
+/// To use a programmer Dvorak, replace the corresponding line by
+///
+/// ```text
+///     xkb_symbols   { include "pc+inet(evdev)+us(dvp)" };
+/// ```
+///
+/// To use a German keymap, replace the corresponding line by
+///
+/// ```text
+///     xkb_symbols   { include "pc+inet(evdev)+de(basic)" };
+/// ```
+///
+/// You can also use a completely custom keymap that doesn't use any includes. See the
+/// [default][default] Jay keymap for an example.
+///
+/// General information about the keymap format can be found in the [arch wiki][wiki].
+///
+/// [default]: https://github.com/mahkoh/jay/tree/master/src/keymap.xkb
+/// [wiki]: https://wiki.archlinux.org/title/X_keyboard_extension
+pub fn parse_keymap(keymap: &str) -> Keymap {
+    get!(Keymap::INVALID).parse_keymap(keymap)
+}