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/map_file.rs

@@ -3,39 +3,88 @@ use serde::Deserialize;
 use eframe::egui::Color32;
 use crate::game::{Board, Element, Glyph, ObjectDef, Player, PortalDef};
 
+/// The top-level deserialization type for a `.toml` map file.
+///
+/// This struct mirrors the TOML file structure exactly and is used only
+/// during loading — it is immediately converted into a [`Board`] via
+/// [`From<MapFile>`] and then discarded. It is never used at runtime.
+///
+/// See `maps/start.toml` for a complete example of the file format.
 #[derive(Deserialize)]
 pub struct MapFile {
+    /// The `[map]` section: name, dimensions, player start position.
     pub map: MapHeader,
+    /// The `[palette]` section: maps single-character keys to tile definitions.
+    /// Each entry defines both the visual ([`Glyph`]) and behavior ([`Element`])
+    /// for all cells that use that character in the grid.
     pub palette: HashMap<String, PaletteEntry>,
+    /// The `[grid]` section: the multi-line string that defines cell layout.
     pub grid: GridData,
+    /// Any `[[objects]]` entries. Optional; defaults to empty.
     #[serde(default)]
     pub objects: Vec<ObjectDef>,
+    /// Any `[[portals]]` entries. Optional; defaults to empty.
     #[serde(default)]
     pub portals: Vec<PortalDef>,
 }
 
+/// The `[map]` header section of a map file.
 #[derive(Deserialize)]
 pub struct MapHeader {
+    /// Human-readable name for this board, e.g. `"Opening Room"`.
+    /// Not yet displayed anywhere at runtime.
     #[allow(dead_code)]
     pub name: String,
+    /// Width of the board in cells. Must match the length of every row in
+    /// `[grid] content`.
     pub width: usize,
+    /// Height of the board in cells. Must match the number of rows in
+    /// `[grid] content`.
     pub height: usize,
+    /// Starting position of the player as `[x, y]` (0-indexed, origin
+    /// top-left). This field will become optional once the player is a
+    /// scripted object rather than a hardcoded entity.
     pub player_start: [i32; 2],
 }
 
+/// One entry in the `[palette]` table.
+///
+/// Each palette entry is keyed by a single character (e.g. `"#"` or `" "`).
+/// That character is used in the `[grid]` content string to place tiles.
+/// The entry defines both how the tile looks (`ch`, `fg`, `bg`) and how it
+/// behaves (`passable`).
+///
+/// Note that `ch` (the display character) does not have to match the palette
+/// key. The key is just a label for the grid; `ch` is what actually gets
+/// rendered. This allows, for example, using `"W"` as the palette key for a
+/// wall tile that displays as `#`.
 #[derive(Deserialize)]
 pub struct PaletteEntry {
+    /// Whether entities can walk onto this tile.
     pub passable: bool,
+    /// The character displayed in this cell.
     pub ch: char,
+    /// Foreground color as an `"#RRGGBB"` hex string.
     pub fg: String,
+    /// Background color as an `"#RRGGBB"` hex string.
     pub bg: String,
 }
 
+/// The `[grid]` section of a map file.
+///
+/// `content` is a TOML multi-line string. Each line is one row of the board;
+/// each character in a line is looked up in the palette to determine the
+/// tile for that cell. TOML automatically strips the newline immediately
+/// following the opening `"""`, so no special handling is needed for a
+/// leading blank line.
 #[derive(Deserialize)]
 pub struct GridData {
+    /// The raw grid content. Split by [`str::lines`] during loading.
     pub content: String,
 }
 
+/// Parses an `"#RRGGBB"` hex color string into a [`Color32`].
+/// Returns black on any parse failure.
 fn parse_color(hex: &str) -> Color32 {
     let hex = hex.trim_start_matches('#');
     if hex.len() != 6 {
@@ -47,11 +96,26 @@ fn parse_color(hex: &str) -> Color32 {
     Color32::from_rgb(r, g, b)
 }
 
+/// Converts a parsed map file into a runtime [`Board`].
+///
+/// The conversion proceeds in two passes:
+///
+/// 1. **Palette pass** — each palette entry becomes an [`Element`] (pushed
+///    into `elements`) and a [`Glyph`] (stored in a temporary `HashMap`
+///    keyed by the palette character). The element index is recorded
+///    alongside the glyph so cells can reference it.
+///
+/// 2. **Grid pass** — `grid.content` is split into lines; each character
+///    is looked up in the palette map. Unknown characters are silently
+///    skipped (they produce no cell), so a malformed grid will result in
+///    a `cells` vec shorter than `width * height`. No explicit validation
+///    is done here yet.
 impl From<MapFile> for Board {
     fn from(mf: MapFile) -> Self {
         let w = mf.map.width;
         let h = mf.map.height;
 
+        // Pass 1: build the element palette and a char→(Glyph, idx) lookup.
         let mut elements: Vec<Element> = Vec::new();
         let mut palette: HashMap<char, (Glyph, usize)> = HashMap::new();
 
@@ -66,6 +130,7 @@ impl From<MapFile> for Board {
             }, idx));
         }
 
+        // Pass 2: walk the grid string and build cells.
         let mut cells: Vec<(Glyph, usize)> = Vec::with_capacity(w * h);
         for line in mf.grid.content.lines() {
             for ch in line.chars() {
@@ -90,6 +155,14 @@ impl From<MapFile> for Board {
     }
 }
 
+/// Loads a map file from disk and returns a ready-to-use [`Board`].
+///
+/// Reads the file at `path`, deserializes it as TOML into a [`MapFile`],
+/// then converts it via [`From<MapFile>`]. Propagates both I/O errors and
+/// TOML parse errors through the `Box<dyn Error>` return.
+///
+/// Called from `main()` before the window is created so that board
+/// dimensions are available for window sizing.
 pub fn load(path: &str) -> Result<Board, Box<dyn std::error::Error>> {
     let content = std::fs::read_to_string(path)?;
     let map_file: MapFile = toml::from_str(&content)?;