From e62722ce2f1175a5d665bf1df7507509345b1d0e Mon Sep 17 00:00:00 2001
From: Danila Fedorin <danila.fedorin@gmail.com>
Date: Fri, 1 Sep 2017 18:32:41 -0700
Subject: [PATCH] Add comments.

---
 .../org/nwapw/abacus/number/NumberUtils.kt    |  6 ++++
 .../nwapw/abacus/number/PromotionManager.kt   | 36 +++++++++++++++++++
 .../nwapw/abacus/number/PromotionResult.kt    |  6 ++++
 3 files changed, 48 insertions(+)

diff --git a/core/src/main/kotlin/org/nwapw/abacus/number/NumberUtils.kt b/core/src/main/kotlin/org/nwapw/abacus/number/NumberUtils.kt
index 5503613..03c46fd 100644
--- a/core/src/main/kotlin/org/nwapw/abacus/number/NumberUtils.kt
+++ b/core/src/main/kotlin/org/nwapw/abacus/number/NumberUtils.kt
@@ -5,6 +5,12 @@ typealias PromotionFunction = java.util.function.Function<NumberInterface, Numbe
 typealias PromotionPath = List<PromotionFunction>
 typealias NumberClass = Class<NumberInterface>
 
+/**
+ * Promote a number through this path. The functions in this path
+ * are applied in order to the number, and the final result is returned.
+ *
+ * @param from the number to start from.
+ */
 fun PromotionPath.promote(from: NumberInterface): NumberInterface {
     return fold(from, { current, function -> function.apply(current) })
 }
\ No newline at end of file
diff --git a/core/src/main/kotlin/org/nwapw/abacus/number/PromotionManager.kt b/core/src/main/kotlin/org/nwapw/abacus/number/PromotionManager.kt
index f4bb684..22e9489 100644
--- a/core/src/main/kotlin/org/nwapw/abacus/number/PromotionManager.kt
+++ b/core/src/main/kotlin/org/nwapw/abacus/number/PromotionManager.kt
@@ -2,12 +2,31 @@ package org.nwapw.abacus.number
 
 import org.nwapw.abacus.Abacus
 import org.nwapw.abacus.plugin.NumberImplementation
+import org.nwapw.abacus.plugin.PluginListener
+import org.nwapw.abacus.plugin.PluginManager
 import java.util.function.Function
 
 class PromotionManager(val abacus: Abacus) {
+/**
+ * A class that handles promotions based on priority and the
+ * transition paths each implementation provides.
+ *
+ * @property abacus the Abacus instance to use to access other components.
+ */
+class PromotionManager(val abacus: Abacus) : PluginListener {
 
+    /**
+     * The already computed paths
+     */
     val computePaths = mutableMapOf<Pair<NumberImplementation, NumberImplementation>, PromotionPath?>()
 
+    /**
+     * Computes a path between a starting and an ending implementation.
+     *
+     * @param from the implementation to start from.
+     * @param to the implementation to get to.
+     * @return the resulting promotion path, or null if it is not found
+     */
     fun computePathBetween(from: NumberImplementation, to: NumberImplementation): PromotionPath? {
         val fromName = abacus.pluginManager.interfaceImplementationNameFor(from.implementation)
         val toName = abacus.pluginManager.interfaceImplementationNameFor(to.implementation)
@@ -19,12 +38,29 @@ class PromotionManager(val abacus: Abacus) {
         return null
     }
 
+    /**
+     * If a path between the given implementations has already been computed, uses
+     * the already calculated path. Otherwise, calls [computePathBetween] to compute a new
+     * path.
+     *
+     * @param from the implementation to start from.
+     * @param to the implementation to get to.
+     * @return the resulting promotion path, or null if it is not found
+     */
     fun getPathBetween(from: NumberImplementation, to: NumberImplementation): PromotionPath? {
         return computePaths.computeIfAbsent(from to to, {
              computePathBetween(it.first, it.second)
         })
     }
 
+    /**
+     * Promote all the numbers in the list to the same number implementation, to ensure
+     * they can be used with each other. Finds the highest priority implementation
+     * in the list, and promotes all other numbers to it.
+     *
+     * @param numbers the numbers to promote.
+     * @return the resulting promotion result.
+     */
     fun promote(vararg numbers: NumberInterface): PromotionResult? {
         val pluginManager = abacus.pluginManager
         val implementations = numbers.map { pluginManager.interfaceImplementationFor(it.javaClass) }
diff --git a/core/src/main/kotlin/org/nwapw/abacus/number/PromotionResult.kt b/core/src/main/kotlin/org/nwapw/abacus/number/PromotionResult.kt
index 2453105..51623fb 100644
--- a/core/src/main/kotlin/org/nwapw/abacus/number/PromotionResult.kt
+++ b/core/src/main/kotlin/org/nwapw/abacus/number/PromotionResult.kt
@@ -2,4 +2,10 @@ package org.nwapw.abacus.number
 
 import org.nwapw.abacus.plugin.NumberImplementation
 
+/**
+ * The result of promoting an array of NumberInterfaces.
+ *
+ * @param promotedTo the implementation to which the numbers were promoted.
+ * @param items the items the items resulting from the promotion.
+ */
 data class PromotionResult(val promotedTo: NumberImplementation, val items: Array<NumberInterface>)
\ No newline at end of file