config: add documentation

jay-config/src/keyboard/keymap.rs

@@ -1,16 +0,0 @@
-use bincode::{Decode, Encode};
-
-#[derive(Encode, Decode, Copy, Clone, Debug, Eq, PartialEq, Hash)]
-pub struct Keymap(pub u64);
-
-impl Keymap {
-    pub const INVALID: Self = Self(0);
-
-    pub fn is_invalid(self) -> bool {
-        self == Self::INVALID
-    }
-}
-
-pub fn parse_keymap(keymap: &str) -> Keymap {
-    get!(Keymap::INVALID).parse_keymap(keymap)
-}

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)
+}

jay-config/src/keyboard/mods.rs

@@ -1,24 +1,39 @@
+//! Keyboard modifiers
+
 use {
     crate::{keyboard::syms::KeySym, ModifiedKeySym},
     bincode::{Decode, Encode},
     std::ops::{BitAnd, BitAndAssign, BitOr, BitOrAssign},
 };
 
+/// Zero or more keyboard modifiers
 #[derive(Encode, Decode, Copy, Clone, Eq, PartialEq, Default, Hash, Debug)]
 pub struct Modifiers(pub u32);
 
+/// The Shift modifier
 pub const SHIFT: Modifiers = Modifiers(1 << 0);
+/// The CapsLock modifier.
 pub const LOCK: Modifiers = Modifiers(1 << 1);
+/// The Ctrl modifier.
 pub const CTRL: Modifiers = Modifiers(1 << 2);
+/// The Mod1 modifier, i.e., Alt.
 pub const MOD1: Modifiers = Modifiers(1 << 3);
+/// The Mod2 modifier, i.e., NumLock.
 pub const MOD2: Modifiers = Modifiers(1 << 4);
+/// The Mod3 modifier.
 pub const MOD3: Modifiers = Modifiers(1 << 5);
+/// The Mod4 modifier, i.e., Logo.
 pub const MOD4: Modifiers = Modifiers(1 << 6);
+/// The Mod5 modifier.
 pub const MOD5: Modifiers = Modifiers(1 << 7);
 
+/// Alias for `LOCK`.
 pub const CAPS: Modifiers = LOCK;
+/// Alias for `MOD1`.
 pub const ALT: Modifiers = MOD1;
+/// Alias for `MOD2`.
 pub const NUM: Modifiers = MOD2;
+/// Alias for `MOD4`.
 pub const LOGO: Modifiers = MOD4;
 
 impl BitOr for Modifiers {

jay-config/src/keyboard/syms.rs

@@ -1,7 +1,10 @@
+//! Keysyms
+
 #![allow(non_upper_case_globals)]
 
 use bincode::{Decode, Encode};
 
+/// A keysym.
 #[derive(Encode, Decode, Copy, Clone, Eq, PartialEq, Hash, Debug)]
 pub struct KeySym(pub u32);