Add comprehensive documentation to dayXX.rs with detailed solution explanations.

These comments were generated using Zed editor with `kimi-k2-0711-preview`` model.

Author: erning

src/day01.rs

@@ -1,3 +1,32 @@
+//! Day 1: Report Repair
+//!
+//! ## Problem Description
+//!
+//! Part 1: Find two numbers in the expense report that sum to 2020 and return their product.
+//! Part 2: Find three numbers in the expense report that sum to 2020 and return their product.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Converts the multiline string input into a vector of integers.
+//!
+//! **Part 1 Strategy**: Uses a brute-force nested loop approach:
+//! - Iterates through all pairs of numbers using two nested loops
+//! - Outer loop: takes each number `a` from the start to second-to-last
+//! - Inner loop: takes each number `b` from current `a` position to end
+//! - Checks if `a + b == 2020`
+//! - Returns `a * b` immediately when found
+//!
+//! **Part 2 Strategy**: Extends the same approach to three numbers:
+//! - Uses three nested loops with similar indexing pattern
+//! - Outer loop: number `a` from start to third-to-last
+//! - Middle loop: number `b` from current `a` position to second-to-last
+//! - Inner loop: number `c` from current `b` position to end
+//! - Checks if `a + b + c == 2020`
+//! - Returns `a * b * c` immediately when found
+//!
+//! **Complexity**: O(n²) for part 1, O(n³) for part 2 where n is the number of entries.
+//! **Optimization Note**: Could be improved with hash sets for O(n) part 1 and O(n²) part 2.
+
 fn parse_input(input: &str) -> Vec<i32> {
     input.trim().lines().map(|s| s.parse().unwrap()).collect()
 }

src/day02.rs

@@ -1,3 +1,35 @@
+//! Day 2: Password Philosophy
+//!
+//! ## Problem Description
+//!
+//! Part 1: Validate passwords based on character count policy - each line contains
+//! a range (min-max), a character, and a password. Count how many passwords
+//! have the character appear between min and max times (inclusive).
+//!
+//! Part 2: Validate passwords based on position policy - each line contains
+//! two positions (1-indexed), a character, and a password. Count how many
+//! passwords have the character appear in exactly one of the two positions.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Parses each line in format "min-max char: password" into:
+//! - Policy tuple: (min_position, max_position, character)
+//! - Password string
+//!
+//! **Part 1 Strategy**: Character frequency counting
+//! - For each password, count occurrences of the specified character
+//! - Check if count falls within the min-max range
+//! - Count valid passwords using iterator filters
+//!
+//! **Part 2 Strategy**: XOR position checking
+//! - Check if character appears at first position (min-1 for 0-indexing)
+//! - Check if character appears at second position (max-1 for 0-indexing)
+//! - Valid when exactly one position contains the character (XOR logic)
+//! - Count valid passwords using iterator filters
+//!
+//! **Parsing Notes**: Uses split on ['-', ' ', ':'] delimiters and careful indexing
+//! to extract policy components and password from each line.
+
 type Policy = (usize, usize, char);
 
 fn parse_input(input: &str) -> Vec<(Policy, &str)> {

src/day03.rs

@@ -1,3 +1,34 @@
+//! Day 3: Toboggan Trajectory
+//!
+//! ## Problem Description
+//!
+//! Part 1: Count trees (#) encountered while sledding down a slope following
+//! a specific path: right 3, down 1. The terrain repeats horizontally.
+//!
+//! Part 2: Multiply the tree counts for multiple slope patterns:
+//! right 1 down 1, right 3 down 1, right 5 down 1, right 7 down 1, right 1 down 2.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Converts each line of the terrain map into a vector of characters,
+//! creating a 2D grid representation.
+//!
+//! **Part 1 Strategy**: Single slope traversal
+//! - Start at top-left position (0,0)
+//! - Move right 3, down 1 repeatedly
+//! - Use modulo arithmetic to handle horizontal repeating pattern
+//! - Count '#' characters encountered
+//!
+//! **Part 2 Strategy**: Multiple slope multiplication
+//! - Apply the same traversal logic to 5 different slope patterns
+//! - Calculate tree count for each slope individually
+//! - Multiply all counts together for final result
+//!
+//! **Grid Traversal**: The `slope` function handles the core logic:
+//! - Takes dx (right movement) and dy (down movement) parameters
+//! - Uses modulo on x-coordinate to handle infinite horizontal repetition
+//! - Returns tree count for the specified slope pattern
+
 fn parse_input(input: &str) -> Vec<Vec<char>> {
     input.trim().lines().map(|s| s.chars().collect()).collect()
 }

src/day04.rs

@@ -1,3 +1,34 @@
+//! Day 4: Passport Processing
+//!
+//! ## Problem Description
+//!
+//! Part 1: Count valid passports based on required fields presence.
+//! Part 2: Count valid passports based on field presence AND field value validation.
+//!
+//! Required fields: byr, iyr, eyr, hgt, hcl, ecl, pid (cid is optional)
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Splits input by double newlines to separate passports,
+//! then parses each passport into a HashMap of field-value pairs.
+//!
+//! **Part 1 Strategy**: Field presence validation
+//! - Checks if all required fields (except cid) are present
+//! - Uses a predefined list of required field keys
+//!
+//! **Part 2 Strategy**: Field value validation
+//! - Applies all Part 1 validations first
+//! - Validates each field value according to specific rules:
+//!   - byr: 1920-2002 (birth year)
+//!   - iyr: 2010-2020 (issue year)
+//!   - eyr: 2020-2030 (expiration year)
+//!   - hgt: 150-193cm or 59-76in (height)
+//!   - hcl: # followed by 6 hex digits (hair color)
+//!   - ecl: one of [amb, blu, brn, gry, grn, hzl, oth] (eye color)
+//!   - pid: 9-digit number (passport ID)
+//!
+//! **Validation Logic**: Uses pattern matching for clean validation of each field type.
+
 use std::collections::HashMap;
 
 fn parse_input(input: &str) -> Vec<HashMap<&str, &str>> {

src/day05.rs

@@ -1,3 +1,32 @@
+//! Day 5: Binary Boarding
+//!
+//! ## Problem Description
+//!
+//! Part 1: Find the highest seat ID on a boarding pass using binary space partitioning.
+//! Part 2: Find your seat ID which is missing from the list but has adjacent seats.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Reads each line as a boarding pass string (e.g., "FBFBBFFRLR").
+//!
+//! **Binary Space Partitioning**: The `decode` function uses binary search:
+//! - 'F'/'L' = take lower half (reduce upper bound)
+//! - 'B'/'R' = take upper half (increase lower bound)
+//! - First 7 chars: row (0-127), Last 3 chars: column (0-7)
+//! - Seat ID = row * 8 + column
+//!
+//! **Part 1 Strategy**: Find maximum seat ID
+//! - Decode all boarding passes to seat IDs
+//! - Return the maximum value
+//!
+//! **Part 2 Strategy**: Find missing seat ID
+//! - Decode all boarding passes and sort seat IDs
+//! - Find gap where seat ID+1 doesn't equal next seat ID
+//! - Return the missing seat ID (your seat)
+//!
+//! **Binary Search Logic**: Uses half-interval search to efficiently determine
+//! row/column from boarding pass characters.
+
 fn parse_input(input: &str) -> Vec<&str> {
     input.trim().lines().collect()
 }

src/day06.rs

@@ -1,3 +1,29 @@
+//! Day 6: Custom Customs
+//!
+//! ## Problem Description
+//!
+//! Part 1: Count the total number of unique questions answered "yes" across all groups.
+//! Part 2: Count the total number of questions answered "yes" by everyone in each group.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Splits input by double newlines to separate groups,
+//! then converts each person's answers into byte slices for efficient processing.
+//!
+//! **Part 1 Strategy**: Union of answers per group
+//! - For each group, track which letters (a-z) appear in any person's answers
+//! - Uses boolean vector as a simple set representation
+//! - Counts unique questions per group and sums across all groups
+//!
+//! **Part 2 Strategy**: Intersection of answers per group
+//! - For each group, count how many people answered each question
+//! - Questions are valid only if count equals group size
+//! - Uses integer vector to track frequency of each letter
+//! - Counts questions answered by everyone per group and sums across all groups
+//!
+//! **Efficiency**: Uses byte arithmetic (ch - b'a') for O(1) character indexing,
+//! avoiding string allocations and leveraging contiguous memory access.
+
 fn parse_input(input: &str) -> Vec<Vec<&[u8]>> {
     input
         .trim()

src/day07.rs

@@ -1,3 +1,29 @@
+//! Day 7: Handy Haversacks
+//!
+//! ## Problem Description
+//!
+//! Part 1: Count how many bag colors can eventually contain at least one "shiny gold" bag.
+//! Part 2: Count how many individual bags are required inside a single "shiny gold" bag.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Creates a directed graph where:
+//! - Nodes are bag colors (e.g., "shiny gold", "dark red")
+//! - Edges represent containment relationships with weights (bag counts)
+//! - Uses nested HashMap: outer map keys are container bags, inner maps store contained bags and their counts
+//!
+//! **Part 1 Strategy**: Reverse traversal (containment check)
+//! - Uses recursive depth-first search to check if any bag can eventually contain "shiny gold"
+//! - For each bag, checks direct containment or recursive containment through any contained bag
+//! - Counts all bags that can reach "shiny gold" (excluding "shiny gold" itself)
+//!
+//! **Part 2 Strategy**: Forward traversal (bag counting)
+//! - Uses recursive depth-first search to count total bags inside "shiny gold"
+//! - For each contained bag: count = quantity * (recursive count of bags inside it + 1)
+//! - Sums all individual bag counts required
+//!
+//! **Algorithm**: Recursive DFS with memoization implicit in function calls handles the tree-like structure efficiently.
+
 use std::collections::HashMap;
 
 fn parse_input(input: &str) -> HashMap<String, HashMap<String, usize>> {

src/day08.rs

@@ -1,3 +1,31 @@
+//! Day 8: Handheld Halting
+//!
+//! ## Problem Description
+//!
+//! Part 1: Find the accumulator value before the program loops infinitely.
+//! Part 2: Fix the program by changing exactly one "jmp" to "nop" or "nop" to "jmp"
+//! so the program terminates normally, then return the accumulator value.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Converts each line into (operation, value) tuples where:
+//! - Operations: "acc" (accumulate), "jmp" (jump), "nop" (no operation)
+//! - Values: signed integers for jump offsets or accumulator changes
+//!
+//! **Part 1 Strategy**: Detect infinite loop
+//! - Execute instructions sequentially while tracking visited positions
+//! - Stop when hitting a previously visited instruction
+//! - Return accumulator value at loop detection point
+//!
+//! **Part 2 Strategy**: Brute-force repair
+//! - Identify all "jmp" and "nop" instructions as candidates for modification
+//! - Try changing each candidate one at a time
+//! - Test if modified program terminates successfully
+//! - Return accumulator value when program reaches end
+//!
+//! **Execution Model**: Uses Result type where Ok() = successful termination,
+//! Err() = infinite loop detected, with accumulator value as payload.
+
 fn parse_input(input: &str) -> Vec<(&str, i32)> {
     input
         .trim()

src/day09.rs

@@ -1,3 +1,27 @@
+//! Day 9: Encoding Error
+//!
+//! ## Problem Description
+//!
+//! Part 1: Find the first number that is NOT the sum of any two of the previous N numbers.
+//! Part 2: Find a contiguous range that sums to the invalid number, then return
+//! the sum of the smallest and largest numbers in that range.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Converts input lines into a vector of unsigned 64-bit integers.
+//!
+//! **Part 1 Strategy**: XMAS cipher validation
+//! - Uses sliding window of previous N numbers (N=5 for example, N=25 for real input)
+//! - For each number, checks if it can be expressed as sum of any two distinct numbers
+//! - Returns the first number that fails this validation
+//!
+//! **Part 2 Strategy**: Contiguous sum search
+//! - Uses sliding window approach to find contiguous range summing to invalid number
+//! - Expands window when sum is too small, shrinks when sum is too large
+//! - Once found, returns sum of min and max values in the contiguous range
+//!
+//! **Window Algorithm**: Efficient O(n) sliding window technique to find contiguous sum.
+
 fn parse_input(input: &str) -> Vec<u64> {
     input.trim().lines().map(|s| s.parse().unwrap()).collect()
 }

src/day10.rs

@@ -1,3 +1,27 @@
+//! Day 10: Adapter Array
+//!
+//! ## Problem Description
+//!
+//! Part 1: Find the product of 1-jolt differences and 3-jolt differences in the adapter chain.
+//! Part 2: Count the total number of distinct ways to arrange the adapters to connect device.
+//!
+//! ## Solution Approach
+//!
+//! **Input Parsing**: Converts input lines into a vector of adapter joltage ratings.
+//!
+//! **Part 1 Strategy**: Joltage difference analysis
+//! - Add charging outlet (0 jolts) and built-in adapter (max + 3 jolts)
+//! - Sort all adapters and calculate differences between consecutive adapters
+//! - Count 1-jolt and 3-jolt differences, return their product
+//!
+//! **Part 2 Strategy**: Dynamic programming for arrangement counting
+//! - Uses DP array where dp[i] = number of ways to reach adapter i
+//! - For each adapter, sum ways from previous adapters within 3-jolt range
+//! - Optimized by working backwards and breaking when range exceeds 3 jolts
+//! - Returns total arrangements to reach the final adapter
+//!
+//! **Algorithm**: Dynamic programming with sliding window optimization for efficient counting.
+
 fn parse_input(input: &str) -> Vec<i32> {
     input.trim().lines().map(|s| s.parse().unwrap()).collect()
 }