More documentation

Author: darkfrog26

shared/src/main/scala/reactify/State.scala

@@ -21,18 +21,37 @@ case class State[T](owner: Reactive[T], index: Long, function: () => T) extends
     ReactionStatus.Continue
   }
 
+  /**
+    * The previous state before this one
+    */
   def previousState: Option[State[T]] = _previousState
 
+  /**
+    * The next state after this one if this is not active
+    */
   def nextState: Option[State[T]] = _nextState
 
+  /**
+    * True if it is the currently active state
+    */
   def active: Boolean = nextState.isEmpty
+
+  /**
+    * The currently active state
+    */
   def activeState: State[T] = nextState match {
     case Some(next) => next.activeState
     case None => this
   }
 
+  /**
+    * Currently cached value derived from state function
+    */
   def cached: Option[T] = _value
 
+  /**
+    * Current value of this state
+    */
   def value: T = {
     StateCounter.referenced(this)
     updatingState match {
@@ -53,8 +72,14 @@ case class State[T](owner: Reactive[T], index: Long, function: () => T) extends
     previousState.flatMap(_.updatingState)
   }
 
+  /**
+    * All states referenced in the function deriving this state's value
+    */
   def references: List[State[_]] = _references
 
+  /**
+    * Updates the derived value of this state
+    */
   def update(previous: Option[State[T]] = _previousState): Unit = synchronized {
     if (!updating.get()) {
       clearReferences()
@@ -108,6 +133,9 @@ case class State[T](owner: Reactive[T], index: Long, function: () => T) extends
     state.owner.asInstanceOf[Reactive[Any]].reactions -= this
   }
 
+  /**
+    * Clears all references to other states from this state
+    */
   def clearReferences(): Unit = synchronized {
     references.foreach(removeReference)
     _references = Nil

shared/src/main/scala/reactify/StateCounter.scala

@@ -28,6 +28,9 @@ object StateCounter {
     }
   }
 
+  /**
+    * Called by a State when it is referenced to get the value
+    */
   def referenced(state: State[_]): Unit = {
     instance.get().foreach { counter =>
       counter.references = state :: counter.references

shared/src/main/scala/reactify/bind/BindSet.scala

@@ -2,8 +2,22 @@ package reactify.bind
 
 sealed trait BindSet
 
+/**
+  * BindSet defines how a binding should be applied when first defined
+  */
 object BindSet {
+  /**
+    * The left value is assigned to the right
+    */
   case object LeftToRight extends BindSet
+
+  /**
+    * The right value is assigned to the left
+    */
   case object RightToLeft extends BindSet
+
+  /**
+    * Values are not modified at bind-time
+    */
   case object None extends BindSet
 }

shared/src/main/scala/reactify/bind/Binding.scala

@@ -3,7 +3,13 @@ package reactify.bind
 import reactify.Var
 import reactify.reaction.Reaction
 
+/**
+  * Binding represents a two-way binding between two `Var`s
+  */
 class Binding[L, R](left: Var[L], right: Var[R], leftToRight: Reaction[L], rightToLeft: Reaction[R]) {
+  /**
+    * Detaches the binding
+    */
   def detach(): Unit = {
     left.reactions -= leftToRight
     right.reactions -= rightToLeft

shared/src/main/scala/reactify/group/Group.scala

@@ -2,6 +2,9 @@ package reactify.group
 
 import reactify.Reactive
 
+/**
+  * Group represents a simple grouping of multiple underlying instances
+  */
 trait Group[T, R <: Reactive[T]] {
   def items: List[R]
 }

shared/src/main/scala/reactify/package.scala

@@ -4,7 +4,7 @@ package object reactify {
   implicit def val2Value[T](v: Val[T]): T = v()
 
   /**
-    * Syntactic sugar for mutating collections in a `StateChannel`
+    * Syntactic sugar for mutating collections in a `Var`
     */
   implicit class ListVar[T](v: Var[List[T]]) {
     def +=(t: T): Unit = v := (v() ::: List(t))

shared/src/main/scala/reactify/reaction/Reaction.scala

@@ -2,8 +2,26 @@ package reactify.reaction
 
 import reactify.Priority
 
+/**
+  * Reaction may be thought of similar to `Observer` or `Listener` in other libraries. A Reaction may be added to a
+  * Reactive in order react when a value is fired upon it.
+  *
+  * @tparam T the type received by this Reaction
+  */
 trait Reaction[T] extends Ordered[Reaction[T]] {
+  /**
+    * Invoked when a new value is received by the associated Reactive
+    *
+    * @param value the new value
+    * @param previous the previous value, if one was defined
+    * @return
+    */
   def apply(value: T, previous: Option[T]): ReactionStatus
+
+  /**
+    * Priority of this Reaction in contrast to other Reactions attached to the same Reactive. A higher value represents
+    * a higher position in reactions list. See Priority for pre-defined values.
+    */
   def priority: Double = Priority.Normal
 
   override def compare(that: Reaction[T]): Int = this.priority.compare(that.priority)

shared/src/main/scala/reactify/reaction/ReactionStatus.scala

@@ -2,7 +2,18 @@ package reactify.reaction
 
 trait ReactionStatus
 
+/**
+  * ReactionStatus is utilized during the propagation of a fired value against a Reactive. This value may be returned by
+  * a Reaction or set via `status` on the Reactive (on the same thread while the fired value is propagating)
+  */
 object ReactionStatus {
+  /**
+    * Continue propagation
+    */
   case object Continue extends ReactionStatus
+
+  /**
+    * Stop propagation
+    */
   case object Stop extends ReactionStatus
 }

shared/src/main/scala/reactify/reaction/Reactions.scala

@@ -1,8 +1,26 @@
 package reactify.reaction
 
+/**
+  * Reactions represents a list of Reaction instances specifically associated with a Reactive
+  */
 trait Reactions[T] {
+  /**
+    * Return all Reactions associated with this Reactive
+    */
   def apply(): List[Reaction[T]]
+
+  /**
+    * Add a Reaction
+    */
   def +=(reaction: Reaction[T]): Reaction[T]
+
+  /**
+    * Remove a Reaction
+    */
   def -=(reaction: Reaction[T]): Boolean
+
+  /**
+    * Remove all Reactions
+    */
   def clear(): Unit
 }

shared/src/main/scala/reactify/transaction/Transaction.scala

@@ -5,6 +5,9 @@ import reactify.Var
 class Transaction {
   private var map = Map.empty[Var[_], TransactionChange]
 
+  /**
+    * Called when the value of a Var changes
+    */
   def change[T](owner: Var[T], oldFunction: () => T, newFunction: () => T): Unit = {
     val change = map.get(owner) match {
       case Some(c) => c.copy(apply = () => owner := newFunction())
@@ -13,50 +16,83 @@ class Transaction {
     map += owner -> change
   }
 
+  /**
+    * Gets the `TransactionChange` for the supplied `Var` if one is defined
+    */
   def get[T](v: Var[T]): Option[TransactionChange] = map.get(v)
 
+  /**
+    * Returns the `TransactionChange` for the supplied `Var` or throws an exception if none exists
+    */
   def apply[T](v: Var[T]): TransactionChange = get(v).getOrElse(throw new RuntimeException(s"No reference in transaction for $v"))
 
+  /**
+    * Commits all changes in this Transaction and then clears the transaction
+    */
   def commit(): Unit = {
     map.keys.foreach { v =>
       commit(v.asInstanceOf[Var[Any]])
     }
     map = Map.empty
   }
 
+  /**
+    * Reverts all changes in this Transaction and then clears the transaction
+    */
   def revert(): Unit = {
     map.keys.foreach { v =>
       revert(v.asInstanceOf[Var[Any]])
     }
     map = Map.empty
   }
 
+  /**
+    * Undoes all changes that occurred within this Transaction. Unlike `revert`, this doesn't clear the transaction.
+    * This allows `redo` to run to re-apply the transaction in the future.
+    */
   def undo(): Unit = {
     map.keys.foreach { v =>
       undo(v.asInstanceOf[Var[Any]])
     }
   }
 
+  /**
+    * Redoes all changes that occurred within this Transaction. Unlike `commit`, this doesn't clear the transaction.
+    * This allows `undo` to un-apply the transaction in the future.
+    */
   def redo(): Unit = {
     map.keys.foreach { v =>
       redo(v.asInstanceOf[Var[Any]])
     }
   }
 
+  /**
+    * Redoes the transaction for this `Var` and then clears it from the transaction.
+    *
+    * @return true if a change was applied
+    */
   def commit[T](v: Var[T]): Boolean = if (redo(v)) {
     map -= v
     true
   } else {
     false
   }
 
+  /**
+    * Undoes the transaction for this `Var` and then clears it from the transaction.
+    *
+    * @return true if a change was applied
+    */
   def revert[T](v: Var[T]): Boolean = if (undo(v)) {
     map -= v
     true
   } else {
     false
   }
 
+  /**
+    * Undoes the transaction for this `Var`.
+    */
   def undo[T](v: Var[T]): Boolean = get(v) match {
     case Some(change) => {
       change.unapply()
@@ -65,6 +101,9 @@ class Transaction {
     case None => false
   }
 
+  /**
+    * Redoes the transaction for this `Var`.
+    */
   def redo[T](v: Var[T]): Boolean = get(v) match {
     case Some(change) => {
       change.apply()
@@ -74,13 +113,26 @@ class Transaction {
   }
 }
 
+/**
+  * Transaction allows access to undo, redo, revert, and commit changes to `Var`s
+  */
 object Transaction {
   private val threadLocal = new ThreadLocal[Option[Transaction]] {
     override def initialValue(): Option[Transaction] = None
   }
 
+  /**
+    * True if a Transaction is currently active on the current thread
+    */
   def active: Boolean = threadLocal.get().nonEmpty
 
+  /**
+    * Creates a new Transaction if one isn't already active or re-uses an existing one if a Transaction is already
+    * in-progress for this thread.
+    *
+    * @param f the function to run within a Transaction
+    * @return Transaction
+    */
   def apply(f: => Unit): Transaction = {
     val created = !active
     val transaction = threadLocal.get().getOrElse {
@@ -95,6 +147,9 @@ object Transaction {
     transaction
   }
 
+  /**
+    * Called when the value of a Var changes
+    */
   def change[T](owner: Var[T], oldFunction: () => T, newFunction: () => T): Unit = {
     threadLocal.get().foreach(_.change(owner, oldFunction, newFunction))
   }