Add rustdoc and inline comments throughout; update CLAUDE.md style guide

All public types, fields, and functions in game.rs and map_file.rs now
have /// doc comments. main.rs has /// on App and draw_glyph plus inline
comments explaining the input/render pipeline. CLAUDE.md records the
expectation that generated code includes comments.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

src/game.rs

@@ -1,57 +1,152 @@
 use eframe::egui::Color32;
 use serde::Deserialize;
 
+/// The visual representation of a single board cell.
+///
+/// `Glyph` holds everything needed to draw one cell on screen: which character
+/// to display and what colors to use. It is stored per-cell (not per element
+/// type), so individual cells can vary their appearance independently — for
+/// example, a field of "fire" tiles where each flame has a slightly different
+/// color while all sharing the same [`Element`] behavior.
+///
+/// `Glyph` values come from the map file palette and are set at load time.
+/// The player is the only entity whose glyph is hardcoded at runtime
+/// (see [`Glyph::player`]).
 #[derive(Clone, Copy)]
 pub struct Glyph {
+    /// The character to display in this cell.
     pub ch: char,
+    /// Foreground (text) color.
     pub fg: Color32,
+    /// Background color, drawn as a filled rectangle behind the character.
     pub bg: Color32,
 }
 
 impl Glyph {
+    /// Returns the glyph used to render the player: `@` in light blue on black.
+    ///
+    /// This is the only hardcoded glyph; all other glyphs come from the map
+    /// file palette. It will be removed once the player becomes a scripted
+    /// object with its own palette entry.
     pub fn player() -> Self {
         Self { ch: '@', fg: Color32::LIGHT_BLUE, bg: Color32::BLACK }
     }
 }
 
+/// The behavioral definition of a tile type.
+///
+/// `Element` describes how a tile *behaves*, independent of how it looks.
+/// Behavior is shared: many cells on the board can reference the same
+/// `Element` by index (see [`Board::elements`]), so changing one `Element`
+/// affects all cells that use it.
+///
+/// The visual side is handled separately by [`Glyph`], which is stored
+/// per-cell and can vary even among cells of the same element type.
 pub struct Element {
+    /// Whether the player (or other entities) can walk onto this tile.
     pub passable: bool,
 }
 
+/// A scripted object placed on the board, loaded from a map file.
+///
+/// `ObjectDef` represents a tile that has Rhai script attached to it.
+/// Scripts can respond to events like the player touching or shooting the
+/// tile. Objects are parsed from `[[objects]]` entries in `.toml` map files
+/// and stored on [`Board`].
+///
+/// **Not yet runtime-wired.** Objects are loaded and stored but their scripts
+/// are not yet executed. Scripting dispatch is a future feature.
 #[derive(Deserialize)]
 #[allow(dead_code)]
 pub struct ObjectDef {
+    /// Column of this object on the board (0-indexed).
     pub x: usize,
+    /// Row of this object on the board (0-indexed).
     pub y: usize,
+    /// The Rhai script source for this object.
     pub script: String,
 }
 
+/// A portal that teleports the player to a named entry point on another board.
+///
+/// Portals are loaded from `[[portals]]` entries in `.toml` map files and
+/// stored on [`Board`]. When the player steps onto a portal's cell, they
+/// should be moved to `target_entry` on the board named by `target_map`.
+///
+/// **Not yet runtime-wired.** Portal navigation (multi-board loading and
+/// switching) is a future feature.
 #[derive(Deserialize)]
 #[allow(dead_code)]
 pub struct PortalDef {
+    /// Column of this portal on the board (0-indexed).
     pub x: usize,
+    /// Row of this portal on the board (0-indexed).
     pub y: usize,
+    /// File name (without extension) of the target board, e.g. `"cave"`.
     pub target_map: String,
+    /// Named entry point on the target board where the player arrives.
     pub target_entry: String,
 }
 
+/// The player's current position on the board.
+///
+/// The player is currently a special entity rendered on top of the board
+/// rather than being stored as a board cell. This is expected to change:
+/// the player will eventually become a scripted object that responds to
+/// input events, at which point this struct may be removed or made optional.
+/// See `ARCHITECTURE.md` for details.
 pub struct Player {
+    /// Column position (0-indexed, increasing rightward).
     pub x: i32,
+    /// Row position (0-indexed, increasing downward).
     pub y: i32,
 }
 
+/// The complete state of one game board (a single room or screen).
+///
+/// `Board` is the central data structure of the engine, equivalent to a
+/// "board" in ZZT. It contains everything needed to represent and run one
+/// self-contained area of the game world:
+///
+/// - A grid of cells, each with a visual ([`Glyph`]) and a behavior index
+/// - A palette of [`Element`] behavior definitions shared across cells
+/// - The current player position
+/// - Scripted objects and portals (loaded but not yet active)
+///
+/// ## Cell storage
+///
+/// Cells are stored as `(Glyph, usize)` tuples in a row-major `Vec`. The
+/// `usize` is an index into [`Board::elements`]. It is an anonymous tuple
+/// field intentionally — the index has no meaning outside the context of
+/// a specific `Board`'s element palette, so it cannot be accidentally
+/// detached and misused.
+///
+/// Access cells with [`Board::get`] and [`Board::get_mut`] using `(x, y)`
+/// coordinates. Use [`Board::is_passable`] for collision checks.
 #[allow(dead_code)]
 pub struct Board {
+    /// Width of the board in cells.
     pub width: usize,
+    /// Height of the board in cells.
     pub height: usize,
+    /// Palette of element behavior definitions. Cells reference these by index.
     pub elements: Vec<Element>,
+    /// Row-major grid of `(Glyph, element_index)` pairs. Use [`Board::get`]
+    /// to access by coordinates.
     pub(crate) cells: Vec<(Glyph, usize)>,
+    /// Current player position. See [`Player`] for caveats about its future.
     pub player: Player,
+    /// Scripted objects on this board. Parsed from the map file; not yet active.
     pub objects: Vec<ObjectDef>,
+    /// Portals on this board. Parsed from the map file; not yet active.
     pub portals: Vec<PortalDef>,
 }
 
 impl Board {
+    /// Adds an element to this board's palette and returns its index.
+    ///
+    /// The returned index can be used as the second field of a cell tuple.
+    /// Indices are stable for the lifetime of the board.
     #[allow(dead_code)]
     pub fn add_element(&mut self, element: Element) -> usize {
         let idx = self.elements.len();
@@ -59,30 +154,54 @@ impl Board {
         idx
     }
 
+    /// Returns a reference to the cell at `(x, y)`.
+    ///
+    /// The cell is a `(Glyph, usize)` tuple where the `usize` is an index
+    /// into [`Board::elements`]. Panics if `x` or `y` are out of bounds.
     pub fn get(&self, x: usize, y: usize) -> &(Glyph, usize) {
         &self.cells[y * self.width + x]
     }
 
+    /// Returns a mutable reference to the cell at `(x, y)`.
+    ///
+    /// Panics if `x` or `y` are out of bounds.
     #[allow(dead_code)]
     pub fn get_mut(&mut self, x: usize, y: usize) -> &mut (Glyph, usize) {
         &mut self.cells[y * self.width + x]
     }
 
+    /// Returns `true` if the element at `(x, y)` is passable.
+    ///
+    /// Panics if `x` or `y` are out of bounds.
     pub fn is_passable(&self, x: usize, y: usize) -> bool {
         let (_, elem_idx) = self.get(x, y);
         self.elements[*elem_idx].passable
     }
 }
 
+/// Holds the active game board and provides game-logic operations.
+///
+/// `GameState` is the boundary between the engine (rendering, input) and the
+/// game data ([`Board`]). It owns the current board and exposes methods for
+/// actions that involve game rules — currently just player movement.
+///
+/// As scripting and event dispatch are added, `GameState` will grow to handle
+/// routing input events to the appropriate Rhai scripts.
 pub struct GameState {
+    /// The currently active board.
     pub board: Board,
 }
 
 impl GameState {
+    /// Creates a `GameState` from a pre-loaded [`Board`].
     pub fn new(board: Board) -> Self {
         Self { board }
     }
 
+    /// Attempts to move the player by `(dx, dy)` cells.
+    ///
+    /// The move is ignored if the target cell is out of bounds or its element
+    /// is not passable. No-ops silently (the caller does not need to check).
     pub fn try_move(&mut self, dx: i32, dy: i32) {
         let nx = self.board.player.x + dx;
         let ny = self.board.player.y + dy;
@@ -95,4 +214,4 @@ impl GameState {
             }
         }
     }
-}
+}