From d5c33e1782a66f7c30f1992eab13d5e2cf33858d Mon Sep 17 00:00:00 2001
From: Matej Focko <me@mfocko.xyz>
Date: Mon, 2 Dec 2024 15:55:40 +0100
Subject: [PATCH] docs(utils): add documentation to functions

Signed-off-by: Matej Focko <me@mfocko.xyz>
---
 src/Utils.kt | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/Utils.kt b/src/Utils.kt
index ff225d2..0ae3d04 100644
--- a/src/Utils.kt
+++ b/src/Utils.kt
@@ -3,7 +3,7 @@ import java.math.BigInteger
 import java.security.MessageDigest
 
 /**
- * Converts string to md5 hash.
+ * Converts string to MD5 hash.
  */
 fun String.md5() =
     BigInteger(1, MessageDigest.getInstance("MD5").digest(toByteArray()))
@@ -15,6 +15,14 @@ fun String.md5() =
  */
 fun Any?.println() = println(this)
 
+/**
+ * Opens file for a requested day with a given name. Useful for parametrizing
+ * the input files, e.g., samples or challenge inputs.
+ *
+ * @param day Day of the AoC challenge
+ * @param name Name of the file, e.g., `input` or `sample`
+ * @return `File` object
+ */
 private fun openFile(
     day: Int,
     name: String,
@@ -28,16 +36,25 @@ fun readInput(
     name: String,
 ) = openFile(day, name).readText().trim().lines()
 
+/**
+ * Reads input as one string.
+ */
 fun readInputAsString(
     day: Int,
     name: String,
 ) = openFile(day, name).readText()
 
+/**
+ * Reads input as line-separated integers.
+ */
 fun readInputAsInts(
     day: Int,
     name: String,
 ) = readInput(day, name).map { it.toInt() }
 
+/**
+ * Reads input as one line of comma-separated integers.
+ */
 fun readInputAsCommaSeparatedInts(
     day: Int,
     name: String,
@@ -46,6 +63,15 @@ fun readInputAsCommaSeparatedInts(
     .split(",")
     .map { it.toInt() }
 
+/**
+ * Reads input representing a graph in a form of
+ *
+ *     u₁-v₁
+ *     u₂-v₂
+ *     u₃-v₃
+ *
+ * where each edge resides on just one line.
+ */
 fun readGraph(
     day: Int,
     name: String,
@@ -57,22 +83,52 @@ fun readGraph(
     currentGraph + mapOf(fromVertex to fromNeighbours, toVertex to toNeighbours)
 }.toMap()
 
+/**
+ * Constructs product of two sequences.
+ *
+ * @param xs First sequence
+ * @param ys Second sequence
+ * @return Sequence of pairs with elements from `xs` and `ys`
+ */
 fun <A, B> product(
     xs: Sequence<A>,
     ys: Sequence<B>,
 ): Sequence<Pair<A, B>> = xs.flatMap { x -> ys.map { y -> x to y } }
 
+/**
+ * Constructs product of three sequences.
+ *
+ * @param xs First sequence
+ * @param ys Second sequence
+ * @param zs Third sequence
+ * @return Sequence of triples with elements from `xs`, `ys` and `zs`
+ */
 fun <A, B, C> product(
     xs: Sequence<A>,
     ys: Sequence<B>,
     zs: Sequence<C>,
 ): Sequence<Triple<A, B, C>> = xs.flatMap { x -> ys.flatMap { y -> zs.map { z -> Triple(x, y, z) } } }
 
+/**
+ * Constructs product of two iterables.
+ *
+ * @param xs First iterable
+ * @param ys Second iterable
+ * @return Sequence of pairs with elements from `xs` and `ys`
+ */
 fun <A, B> product(
     xs: Iterable<A>,
     ys: Iterable<B>,
 ): Sequence<Pair<A, B>> = product(xs.asSequence(), ys.asSequence())
 
+/**
+ * Constructs product of three iterables.
+ *
+ * @param xs First iterable
+ * @param ys Second iterable
+ * @param zs Third iterable
+ * @return Sequence of triples with elements from `xs`, `ys` and `zs`
+ */
 fun <A, B, C> product(
     xs: Iterable<A>,
     ys: Iterable<B>,