Added documentation

Author: darkfrog26

shared/src/main/scala/reactify/Channel.scala

@@ -6,21 +6,61 @@ import reactify.standard.StandardChannel
 import scala.concurrent.Future
 import scala.concurrent.ExecutionContext.Implicits.global
 
+/**
+  * Channel is a stateless Reactive implementation exposing a public method to fire values.
+  *
+  * @tparam T the type of value this Reactive receives
+  */
 trait Channel[T] extends Reactive[T] {
+  /**
+    * Public method to fire a value against the Reactions attached to this Channel
+    *
+    * @param value the function value
+    */
   def set(value: => T): Unit
+
+  /**
+    * Convenience method to fire a value
+    *
+    * @see #set
+    * @param value the function value
+    */
   def :=(value: => T): Unit = set(value)
+
+  /**
+    * Convenience functionality to assign the result of a future (upon completion) to this Channel
+    */
   def !(future: Future[T]): Future[Unit] = future.map { value =>
     set(value)
   }
 
+  /**
+    * Group multiple channels together
+    */
   def and(that: Channel[T]): Channel[T] = ChannelGroup(None, List(this, that))
 
+  /**
+    * Functional mapping of this Channel into another Channel. All values received by this Channel will be mapped and
+    * forwarded to the new Channel.
+    *
+    * @param f conversion function
+    * @tparam R the type of the new Channel
+    * @return Channel[R]
+    */
   def map[R](f: T => R): Channel[R] = {
     val channel = Channel[R]
     attach(channel := f(_))
     channel
   }
 
+  /**
+    * Functional collection of this Channel into another Channel. All values received by this Channel will be collected
+    * and forwarded to the new Channel if they are collected by the conversion function.
+    *
+    * @param f conversion partial function
+    * @tparam R the type of the Channel
+    * @return Channel[R]
+    */
   def collect[R](f: PartialFunction[T, R]): Channel[R] = {
     val channel = Channel[R]
     val lifted = f.lift

shared/src/main/scala/reactify/Dep.scala

@@ -1,8 +1,26 @@
 package reactify
 
-import reactify.reaction.{Reaction, ReactionStatus}
 import reactify.standard.StandardDep
 
+/**
+  * Dep allows creation of a dependent `Var` on another `Var` allowing conversion between the two. This can be useful for
+  * different representations of the same value. For example, in a graphical environment `left`, `center`, and `right`
+  * are all different representations of the value (horizontal position). Maintaining three distinct values while
+  * keeping them in-sync is painful. With `Dep` you can simply define one `Var` and two `Dep` values like:
+  *
+  * <code>
+  *   val left: Var[Double] = Var(0.0)
+  *   val width: Var[Double] = Var(0.0)
+  *   val center: Dep[Double, Double] = Dep(left)(_ + (width / 2.0), _ - (width / 2.0))
+  *   val right: Dep[Double, Double] = Dep(left)(_ + width, _ - width)
+  * </code>
+  *
+  * Now, modification to `left`, `center`, or `right` will maintain the appropriate value for each without any additional
+  * boilerplate.
+  *
+  * @tparam T the type of value this Reactive receives
+  * @tparam R the type that this Dep receives
+  */
 trait Dep[T, R] extends Var[T] {
   def owner: Var[R]
   def t2R(t: T): R

shared/src/main/scala/reactify/Priority.scala

@@ -1,5 +1,8 @@
 package reactify
 
+/**
+  * Convenience values for Priorities
+  */
 object Priority {
   val Lowest: Double = Double.MinValue
   val Low: Double = -100.0

shared/src/main/scala/reactify/Reactive.scala

@@ -6,32 +6,82 @@ import reactify.standard.StandardReactions
 import scala.annotation.tailrec
 import scala.concurrent.{Future, Promise}
 
+/**
+  * Reactive is the core trait for Reactify. The basic premise is that a Reactive represents an instance that can attach
+  * Reactions and fire instances of `T` that are received by those Reactions.
+  *
+  * @tparam T the type of value this Reactive receives
+  */
 trait Reactive[T] {
+  /**
+    * An optional name associated. This is primarily used for distinguishing between instances as well as logging.
+    */
   def name: Option[String]
+
   private lazy val _status = new ThreadLocal[Option[ReactionStatus]]
 
+  /**
+    * If the current thread is reacting to a value currently, status represents the status of the reaction. This can be
+    * set to ReactionStatus.Stop in order to stop propagation. This can also be achieved via stopPropagation().
+    */
   def status: Option[ReactionStatus] = _status.get()
   def status_=(status: ReactionStatus): Unit = {
     assert(_status.get().nonEmpty, "Cannot set the status without an active reaction on this thread")
     _status.set(Some(status))
   }
 
+  /**
+    * Shortcut functionality to call `status = ReactionStatus.Stop`
+    */
   def stopPropagation(): Unit = status = ReactionStatus.Stop
 
+  /**
+    * Reactions currently associated with this Reactive
+    */
   lazy val reactions: Reactions[T] = new StandardReactions[T]
 
+  /**
+    * Convenience method to create a Reaction to attach to this Reactive
+    *
+    * @param f the function reaction
+    * @param priority the priority in comparison to other reactions (Defaults to Priority.Normal)
+    * @return created Reaction[T]
+    */
   def attach(f: T => Unit, priority: Double = Priority.Normal): Reaction[T] = {
     reactions += Reaction[T](f, priority)
   }
 
+  /**
+    * Convenience method to create a Reaction to monitor changes to this Reactive
+    *
+    * @param f the function reaction to receive changes
+    * @param priority the priority in comparison to other reactions (Defaults to Priority.Normal)
+    * @return created Reaction[T]
+    */
   def changes(f: (T, T) => Unit, priority: Double = Priority.Normal): Reaction[T] = {
     reactions += Reaction.changes[T](f, priority)
   }
 
+  /**
+    * Convenience method to create a Reaction to monitor changes to this Reactive when you don't care about the actual
+    * value.
+    *
+    * @param f the function reaction to invoke in reaction to a value received
+    * @param priority the priority in comparison to other reactions (Defaults to Priority.Normal)
+    * @return created Reaction[T]
+    */
   def on(f: => Unit, priority: Double = Priority.Normal): Reaction[T] = {
     attach(_ => f, priority)
   }
 
+  /**
+    * Convenience method to create a Reaction to monitor a single reaction based on an optional condition.
+    *
+    * @param f the function reaction
+    * @param condition optional condition that must be true for this to fire (Defaults to accept anything)
+    * @param priority the priority in comparison to other reactions (Defaults to Priority.Normal)
+    * @return created Reaction[T]
+    */
   def once(f: T => Unit, condition: T => Boolean = _ => true, priority: Double = Priority.Normal): Reaction[T] = {
     var reaction: Reaction[T] = null
     val function = (t: T) => if (condition(t)) {
@@ -43,12 +93,22 @@ trait Reactive[T] {
     reaction
   }
 
+  /**
+    * Convenience method to create a `Future[T]` that will complete upon the next reaction that meets to supplied
+    * condition.
+    *
+    * @param condition optional condition that must be true for this to fire (Defaults to accept anything)
+    * @return Future[T]
+    */
   def future(condition: T => Boolean = _ => true): Future[T] = {
     val promise = Promise[T]
     once(promise.success, condition)
     promise.future
   }
 
+  /**
+    * Fires the value to the Reactions
+    */
   protected def fire(value: T, previous: Option[T], reactions: List[Reaction[T]] = this.reactions()): ReactionStatus = {
     _status.set(Some(ReactionStatus.Continue))
     try {
@@ -77,7 +137,7 @@ trait Reactive[T] {
 }
 
 object Reactive {
-  def fire[T](reactive: Reactive[T], value: T, previous: Option[T]): Unit = {
+  private[reactify] def fire[T](reactive: Reactive[T], value: T, previous: Option[T]): Unit = {
     reactive.fire(value, previous, reactive.reactions())
   }
 }

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

@@ -2,6 +2,9 @@ package reactify
 
 import reactify.reaction.{Reaction, ReactionStatus}
 
+/**
+  * State is an internal class to represent the assigned state of a `Val`, `Var`, or `Dep`
+  */
 case class State[T](owner: Reactive[T], index: Long, function: () => T) extends Reaction[Any] {
   private var _previousState: Option[State[T]] = None
   private var _nextState: Option[State[T]] = None

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

@@ -4,11 +4,18 @@ class StateCounter {
   var references: List[State[_]] = Nil
 }
 
+/**
+  * StateCounter provides infrastructure to glean the references to `State`s within a functional block of code. This is
+  * primarily for internal use, but can be used externally to get additional information regarding references.
+  */
 object StateCounter {
   private val instance = new ThreadLocal[Option[StateCounter]] {
     override def initialValue(): Option[StateCounter] = None
   }
 
+  /**
+    * Use this method to get a list of `State` references used by the underlying function block
+    */
   def transaction[Return](f: => Return): (Return, List[State[_]]) = {
     val previous = instance.get()
     val counter = new StateCounter

shared/src/main/scala/reactify/Trigger.scala

@@ -2,6 +2,10 @@ package reactify
 
 import reactify.standard.StandardChannel
 
+/**
+  * Trigger is a convenience class wrapping `Channel[Unit]` specifically for scenarios where the value doesn't matter,
+  * just the reactions themselves.
+  */
 trait Trigger extends Channel[Unit] {
   def trigger(): Unit = fire((), None)
 }

shared/src/main/scala/reactify/Val.scala

@@ -3,14 +3,40 @@ package reactify
 import reactify.group.ValGroup
 import reactify.standard.StandardVal
 
+/**
+  * Val represents a final variable that cannot be set apart from its instantiation. However, unlike a Scala `val`, a
+  * `Val` may still fire changes if its value is derived from `Var`s that make it up. A `Val` is a stateful `Reactive`.
+  *
+  * @tparam T the type of value this Reactive receives
+  */
 trait Val[T] extends Reactive[T] {
+  /**
+    * The current State representation
+    */
   def state: State[T]
 
+  /**
+    * Gets the current value from the current `State`
+    */
   def get: T = state.value
+
+  /**
+    * Convenience wrapper around `get`
+    */
   def apply(): T = get
 
+  /**
+    * Group multiple Vals together
+    */
   def and(that: Val[T]): Val[T] = ValGroup[T](None, List(this, that))
 
+  /**
+    * Functional mapping of this Val into another Val.
+    *
+    * @param f conversion function
+    * @tparam R the type of the new Val
+    * @return Val[R]
+    */
   def map[R](f: T => R): Val[R] = Val[R](f(get))
 
   override def toString: String = name.getOrElse("Val")

shared/src/main/scala/reactify/Var.scala

@@ -7,21 +7,53 @@ import reactify.group.VarGroup
 import reactify.reaction.Reaction
 import reactify.standard.StandardVar
 
+/**
+  * Var represents the combination of `Val` and `Channel` into a stateful and mutable underlying value.
+  *
+  * @tparam T the type of value this Reactive receives
+  */
 trait Var[T] extends Val[T] with Channel[T] {
+  /**
+    * Convenience functionality to attach a Reaction and immediately fire the current state on the Reaction.
+    *
+    * @param f the function reaction
+    * @param priority the priority in comparison to other reactions (Defaults to Priority.Normal)
+    * @return Reaction[T]
+    */
   def attachAndFire(f: T => Unit, priority: Double = Priority.Normal): Reaction[T] = {
     val reaction = attach(f, priority)
-    fire(get, Some(get), reactions())
+    fire(get, Some(get), List(reaction))
     reaction
   }
 
+  /**
+    * Group multiple Vars together
+    */
   def and(that: Var[T]): Var[T] = VarGroup[T](None, List(this, that))
 
+  /**
+    * Functional mapping of this Var into another Var.
+    *
+    * @param f conversion function
+    * @tparam R the type of the new Var
+    * @return Var[R]
+    */
   override def map[R](f: T => R): Var[R] = {
     val v = Var[R](f(get))
     attach(v := f(_))
     v
   }
 
+  /**
+    * Convenience method to create a binding between two `Var`s
+    *
+    * @param that the second `Var` to bind between
+    * @param setNow the `BindSet` value (Defaults to LeftToRight)
+    * @param t2v implicit function conversion from T to V
+    * @param v2t implicit function conversion from V to T
+    * @tparam V the type of the second `Var`
+    * @return Binding[T, V]
+    */
   def bind[V](that: Var[V], setNow: BindSet = BindSet.LeftToRight)
              (implicit t2v: T => V, v2t: V => T): Binding[T, V] = {
     setNow match {

shared/src/test/scala/test/DepSpec.scala

@@ -165,4 +165,4 @@ class DepSpec extends WordSpec with Matchers {
       ))
     }
   }
-}
+}