From d5057fc4d578fba728a3ee70d9ba73e84a8a6772 Mon Sep 17 00:00:00 2001
From: tchojnacki <tomaszchojnacki2001@gmail.com>
Date: Fri, 3 Dec 2021 14:47:43 +0100
Subject: Improve documentation

---
 src/Day03.kt | 71 +++++++++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 51 insertions(+), 20 deletions(-)

(limited to 'src/Day03.kt')

diff --git a/src/Day03.kt b/src/Day03.kt
index c64da47..94b1bf4 100644
--- a/src/Day03.kt
+++ b/src/Day03.kt
@@ -1,30 +1,61 @@
-fun main() {
-    fun addLists(l1: List<Int>, l2: List<Int>): List<Int> = l1.zip(l2).map { it.first + it.second }
-
-    fun valueOfBits(bitList: List<Int>): Int = bitList.reduce { acc, bit -> acc * 2 + bit }
+/**
+ * Add two lists element by element.
+ * @param l1 first list
+ * @param l2 second list
+ * @return a new list, where each element at index `i` is equal to `l1.get(i) + l2.get(i)`
+ */
+fun addLists(l1: List<Int>, l2: List<Int>): List<Int> = l1.zip(l2).map { it.first + it.second }
 
-    fun invertBits(bitList: List<Int>): List<Int> = bitList.map { bit -> 1 - bit }
+/**
+ * Returns the decimal value of a binary number represented as a list of bits.
+ * @param bitList list of bits
+ * @return decimal value of binary number
+ */
+fun valueOfBits(bitList: List<Int>): Int = bitList.reduce { acc, bit -> acc * 2 + bit }
 
-    fun mostCommonBits(input: List<List<Int>>): List<Int> =
-        input
-            .reduce(::addLists)
-            .map { bit -> if (bit.toDouble() / input.size >= 0.5) 1 else 0 }
+/**
+ * Invert all bits of a binary number.
+ * @param bitList list of bits
+ * @return list of bits, where each bit of [bitList] is flipped
+ */
+fun invertBits(bitList: List<Int>): List<Int> = bitList.map { bit -> 1 - bit }
 
-    fun selectByBitCriteria(
-        input: List<List<Int>>,
-        comparisonCriteria: (currentList: List<List<Int>>) -> List<Int>
-    ): List<Int>? {
-        var list = input
-        var index = 0
+/**
+ * Given a list of binary numbers (represented as a list of bits) return a binary number,
+ * where each bit has the value most common at that position among the numbers in the list.
+ * @param input list of lists of bits
+ * @return list of bits, where each bit has the most common value in the corresponding position of all numbers in the list
+ */
+fun mostCommonBits(input: List<List<Int>>): List<Int> =
+    input
+        .reduce(::addLists)
+        .map { bit -> if (bit.toDouble() / input.size >= 0.5) 1 else 0 }
 
-        while (list.size > 1 && index < list[0].size) {
-            list = list.filter { e -> e[index] == comparisonCriteria(list)[index] }
-            index += 1
-        }
+/**
+ * Find a binary number from a list, by filtering out values until one remains.
+ * While the list has more than one number, remove numbers having a different bit
+ * value at current position (starting at 0, increased by 1 after each filtering)
+ * then the value at corresponding position in the `comparisonCriteria(currentList)` list.
+ * @param input list used to search for the value
+ * @param comparisonCriteria function returning a binary number used to compare with others for filtering
+ * @return found binary number represented as a list of bits
+ */
+fun selectByBitCriteria(
+    input: List<List<Int>>,
+    comparisonCriteria: (currentList: List<List<Int>>) -> List<Int>
+): List<Int>? {
+    var list = input
+    var index = 0
 
-        return list.getOrNull(0)
+    while (list.size > 1 && index < list[0].size) {
+        list = list.filter { e -> e[index] == comparisonCriteria(list)[index] }
+        index += 1
     }
 
+    return list.getOrNull(0)
+}
+
+fun main() {
     fun part1(input: List<List<Int>>): Int =
         mostCommonBits(input)
             .let { gammaBits ->
-- 
cgit v1.2.3