Improve documentation

3 files changed, 79 insertions, 29 deletions

diff --git a/src/Day02.kt b/src/Day02.kt
index 1b4bfad..401c508 100644
--- a/src/Day02.kt
+++ b/src/Day02.kt
@@ -1,14 +1,19 @@
-fun main() {
-    fun dispatchCommands(commands: List<String>, action: (command: String, argument: Int) -> Unit) {
-        for (line in commands) {
-            val parts = line.split(" ")
-            val command = parts[0]
-            val argument = parts[1].toInt()
-
-            action(command, argument)
-        }
+/**
+ * Given a list of correct command strings, dispatch [action] taking command name and argument on each of them.
+ * @param commands list of valid command strings
+ * @param action function taking a string (command name) and integer (argument) that gets called for each command
+ */
+fun dispatchCommands(commands: List<String>, action: (command: String, argument: Int) -> Unit) {
+    for (line in commands) {
+        val parts = line.split(" ")
+        val command = parts[0]
+        val argument = parts[1].toInt()
+
+        action(command, argument)
     }
+}
 
+fun main() {
     fun part1(input: List<String>): Int {
         var horizontal = 0
         var depth = 0
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 ->
diff --git a/src/Utils.kt b/src/Utils.kt
index 23eacb9..27b88b5 100644
--- a/src/Utils.kt
+++ b/src/Utils.kt
@@ -4,16 +4,30 @@ import java.security.MessageDigest
 
 /**
  * Reads lines from the given input txt file.
+ * @param name name of the file
+ * @return list of strings containing line contents
  */
 fun readInputAsLines(name: String): List<String> = File("src", "$name.txt").readLines()
 
+/**
+ * Read lines from the given input txt file and convert them to decimal numbers.
+ * @param name name of the file
+ * @return list of ints containing numbers from each of file's lines
+ */
 fun readInputAsNumbers(name: String): List<Int> = readInputAsLines(name).map { it.toInt() }
 
+/**
+ * Read lines from the given input txt file containing binary numbers and convert them to lists of bits.
+ * @param name name of the file
+ * @return list of lists of ints, where each inner list represents bits of one line of input
+ */
 fun readInputAsBitLists(name: String): List<List<Int>> =
     readInputAsLines(name)
         .map { binaryString -> binaryString.toList().map { bit -> bit.toString().toInt() } }
 
 /**
  * Converts string to md5 hash.
+ * @receiver a string
+ * @return md5 hash of receiver
  */
 fun String.md5(): String = BigInteger(1, MessageDigest.getInstance("MD5").digest(toByteArray())).toString(16)