From cae5cbb10150488beba3cad299fb5c0edf0fd44f Mon Sep 17 00:00:00 2001
From: alexo <the.onga@gmail.com>
Date: Fri, 29 Dec 2023 22:26:46 +1100
Subject: [PATCH] docs: day01

---
 day01/day1a.py            | 37 ++++++++++++++++++++++++++++++++++++-
 day01/day1b.py            | 31 +++++++++++++++++++++++++++++++
 day01/tests/test_day1a.py |  3 +++
 day01/tests/test_day1b.py |  4 ++++
 4 files changed, 74 insertions(+), 1 deletion(-)

diff --git a/day01/day1a.py b/day01/day1a.py
index 9e45b54..8c02029 100644
--- a/day01/day1a.py
+++ b/day01/day1a.py
@@ -1,4 +1,6 @@
-"""day1a solution"""
+"""
+day1a solution
+"""
 
 
 from typing import Optional
@@ -8,6 +10,19 @@
 
 
 def get_first_last(line: str) -> tuple[str, str]:
+    """
+    Returns first and last numeric character of a string
+    It can be the same character
+
+    Args:
+        line (str): string to parse
+
+    Raises:
+        ValueError: When there are no numbers in the string
+
+    Returns:
+        tuple[str, str]: first char, last char
+    """
     first: Optional[str] = None
     last: str
     for char in line:
@@ -22,11 +37,30 @@ def get_first_last(line: str) -> tuple[str, str]:
 
 
 def get_input(input_file: str) -> list[str]:
+    """
+    Grabs list of lines to parse from input file
+
+    Args:
+        input_file (str): input file's name
+
+    Returns:
+        list[str]: list of lines to parse
+    """
+
     with open(input_file, "r", encoding="utf8") as file:
         return list(file)
 
 
 def part1(lines: list[str]) -> int:
+    """
+    Runs day1/part1 of adventofcode2023
+
+    Args:
+        lines (list[str]): list of lines to parse
+
+    Returns:
+        int: sum of results for each line.
+    """
     total = 0
     for line in lines:
         first, last = get_first_last(line)
@@ -36,6 +70,7 @@ def part1(lines: list[str]) -> int:
 
 
 def main() -> None:
+    """Grabs input then processes it"""
     lines = get_input(INPUT)
     print(part1(lines))
 
diff --git a/day01/day1b.py b/day01/day1b.py
index 1af9bfa..f8e04fa 100644
--- a/day01/day1b.py
+++ b/day01/day1b.py
@@ -38,6 +38,18 @@ class WordNumber:
 
 
 def process_line(line: str) -> int:
+    """
+    Processes a line, returning the first and last integer
+    substrings like ``nine`` and ``one`` count as integers,
+    as do ``1`` and ``9``
+
+    Args:
+        line (str): a line to process
+
+    Returns:
+        int: integer value of the two numbers concatenated
+    """
+
     index_to_chars = {}
     for index, char in enumerate(line):
         if char.isnumeric():
@@ -56,16 +68,35 @@ def process_line(line: str) -> int:
 
 
 def get_input(input_file: str) -> list[str]:
+    """
+    Opens a file and returns a list of strings to handle
+
+    Args:
+        input_file (str): filepath of input
+
+    Returns:
+        list[str]: list of strings to parse
+    """
     with open(input_file, "r", encoding="utf8") as file:
         return list(file)
 
 
 def part2(lines: list[str]) -> int:
+    """
+    Returns sum of "first/last" numbers in line
+
+    Args:
+        lines (list[str]): list of lines to handle
+
+    Returns:
+        int: sum of "first/last" numbers in line
+    """
     total = sum(process_line(line) for line in lines)
     return total
 
 
 def main() -> None:
+    """Grabs input and then processes it"""
     lines = get_input(INPUT)
     print(part2(lines))
 
diff --git a/day01/tests/test_day1a.py b/day01/tests/test_day1a.py
index 27e1428..32e7db0 100644
--- a/day01/tests/test_day1a.py
+++ b/day01/tests/test_day1a.py
@@ -4,6 +4,7 @@
 
 
 def test_get_first_last() -> None:
+    """Tests a variety of strings on ``get_first_last()`` function"""
     assert get_first_last("abcdef123asdf4") == ("1", "4")
     assert get_first_last("1") == ("1", "1")
     assert get_first_last("01") == ("0", "1")
@@ -18,11 +19,13 @@ def test_get_first_last() -> None:
 
 
 def test_part1() -> None:
+    """Tests ``part1()`` function"""
     lines: list[str] = get_input(INPUT_SMALL)
     assert part1(lines) == 142
 
 
 def test_get_input() -> None:
+    """Tests ``get_input`` function"""
     lines: list[str] = get_input(INPUT_SMALL)
     assert len(lines) == 4
     assert lines[0].strip() == "1abc2"
diff --git a/day01/tests/test_day1b.py b/day01/tests/test_day1b.py
index 190d67a..4bb402a 100644
--- a/day01/tests/test_day1b.py
+++ b/day01/tests/test_day1b.py
@@ -2,6 +2,7 @@
 
 
 def test_process_line() -> None:
+    """Tests ``process_line()`` function"""
     assert process_line("two1nine") == 29
     assert process_line("eightwothree") == 83
     assert process_line("abcone2threexyz") == 13
@@ -13,16 +14,19 @@ def test_process_line() -> None:
 
 
 def test_get_input() -> None:
+    """Tests ``get_input()`` function"""
     lines: list[str] = get_input(INPUT_SMALL)
     assert len(lines) == 7
     assert lines[0].strip() == "two1nine"
 
 
 def test_index_value() -> None:
+    """Tests ``index_value`` class"""
     index_val: IndexValue = IndexValue(0, "1")
     assert str(index_val) == ("(i:0, v:1)")
 
 
 def test_part2() -> None:
+    """Tests ``part2()`` function"""
     lines: list[str] = get_input(INPUT_SMALL)
     assert part2(lines) == 281