From 4c360728495a8622c4dcd34807924b8fced25aae Mon Sep 17 00:00:00 2001
From: Andras Slemmer <andras.slemmer@r3cev.com>
Date: Tue, 30 Aug 2016 11:22:37 +0100
Subject: [PATCH] client: Document fx utilities

---
 .../r3corda/client/fxutils/AggregatedList.kt  | 24 +++++++++++++++++--
 .../r3corda/client/fxutils/AmountBindings.kt  |  3 +++
 .../com/r3corda/client/fxutils/ChosenList.kt  | 15 +++++++++---
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/client/src/main/kotlin/com/r3corda/client/fxutils/AggregatedList.kt b/client/src/main/kotlin/com/r3corda/client/fxutils/AggregatedList.kt
index 55425cc662..26084a285b 100644
--- a/client/src/main/kotlin/com/r3corda/client/fxutils/AggregatedList.kt
+++ b/client/src/main/kotlin/com/r3corda/client/fxutils/AggregatedList.kt
@@ -7,8 +7,28 @@ import javafx.collections.transformation.TransformationList
 import kotlin.comparisons.compareValues
 
 /**
- * [AggregatedList] provides an [ObservableList] that is an aggregate of the underlying list based on key [K].
- * Internally it uses a sorted list TODO think of a more efficient representation
+ * Given an [ObservableList]<[E]>s and a grouping key [K], [AggregatedList] groups the elements by the key into a fresh
+ * [ObservableList] for each group and exposes the groups as an observable list of [A]s by calling [assemble] on each group.
+ *
+ * Changes done to elements of the input list are reflected in the observable list  of the respective group, whereas
+ * additions/removals of elements in the underlying list are reflected in the exposed [ObservableList]<[A]> by
+ * adding/deleting aggregations as expected.
+ *
+ * The ordering of the exposed list is based on the [hashCode] of keys.
+ *
+ * Example:
+ *   val statesGroupedByCurrency = AggregatedList(states, { state -> state.currency }) { currency, group ->
+ *     object {
+ *       val currency = currency
+ *       val states = group
+ *     }
+ *   }
+ *
+ * The above creates an observable list of (currency, statesOfCurrency) pairs.
+ *
+ * @param list The underlying list.
+ * @param toKey Function to extract the key from an element.
+ * @param assemble Function to assemble the aggregation into the exposed [A].
  */
 class AggregatedList<A, E, K : Any>(
         list: ObservableList<out E>,
diff --git a/client/src/main/kotlin/com/r3corda/client/fxutils/AmountBindings.kt b/client/src/main/kotlin/com/r3corda/client/fxutils/AmountBindings.kt
index ea3c517331..cba9427136 100644
--- a/client/src/main/kotlin/com/r3corda/client/fxutils/AmountBindings.kt
+++ b/client/src/main/kotlin/com/r3corda/client/fxutils/AmountBindings.kt
@@ -10,6 +10,9 @@ import org.fxmisc.easybind.EasyBind
 import java.util.*
 import java.util.stream.Collectors
 
+/**
+ * Utility bindings for the [Amount] type, similar in spirit to [Bindings]
+ */
 class AmountBindings {
     companion object {
         fun <T> sum(amounts: ObservableList<Amount<T>>, token: T) = EasyBind.map(
diff --git a/client/src/main/kotlin/com/r3corda/client/fxutils/ChosenList.kt b/client/src/main/kotlin/com/r3corda/client/fxutils/ChosenList.kt
index 3f98811283..1c33e2a3bb 100644
--- a/client/src/main/kotlin/com/r3corda/client/fxutils/ChosenList.kt
+++ b/client/src/main/kotlin/com/r3corda/client/fxutils/ChosenList.kt
@@ -7,9 +7,18 @@ import javafx.collections.ObservableList
 import javafx.collections.ObservableListBase
 
 /**
- * [ChosenList] is essentially a monadic join of an [ObservableValue] of an [ObservableList] into an [ObservableList].
- * Whenever the underlying [ObservableValue] changes the exposed list changes to the new value. Changes to the list are
- * simply propagated.
+ * [ChosenList] manages an [ObservableList] that may be changed by the wrapping [ObservableValue]. Whenever the underlying
+ * [ObservableValue] changes the exposed list changes to the new value. Changes to the list are simply propagated.
+ *
+ * Example:
+ *   val filteredStates = ChosenList(EasyBind.map(filterCriteriaType) { type ->
+ *     when (type) {
+ *       is (ByCurrency) -> statesFilteredByCurrency
+ *       is (ByIssuer) -> statesFilteredByIssuer
+ *     }
+ *   })
+ *
+ * The above will create a list that chooses and delegates to the appropriate filtered list based on the type of filter.
  */
 class ChosenList<E>(
         private val chosenListObservable: ObservableValue<ObservableList<E>>