Expand map interface, add some docs.

Author: Cantor Chron

src/main/scala/scala/reactive/container/RCell.scala

@@ -7,12 +7,27 @@ import scala.reflect.ClassTag
 
 
 
+/** The reactive cell abstraction represents a mutable memory location
+ *  whose changes may produce events.
+ *
+ *  An `RCell` is conceptually similar to a reactive emitter lifted into a signal.
+ *
+ *  @tparam T         the type of the values it stores
+ *  @param value      the initial value of the reactive cell
+ */
 class RCell[@spec(Int, Long, Double) T](private var value: T)
 extends Signal.Default[T] with ReactMutable {
   self =>
 
+  /** Returns the current value in the reactive cell.
+   */
   def apply(): T = value
 
+  /** Assigns a new value to the reactive cell,
+   *  and emits an event with the new value to all the subscribers.
+   *
+   *  @param v        the new value
+   */
   def :=(v: T): Unit = {
     value = v
     reactAll(v)
@@ -24,6 +39,8 @@ extends Signal.Default[T] with ReactMutable {
 
 object RCell {
 
+  /** A factory method for creating reactive cells.
+   */
   def apply[@spec(Int, Long, Double) T](x: T) = new RCell[T](x)
 
 }

src/main/scala/scala/reactive/container/RHashMap.scala

@@ -231,6 +231,8 @@ extends RMap[K, V] with RBuilder[(K, V), RHashMap[K, V]] with PairBuilder[K, V,
 
   private def noKeyError(key: K) = throw new NoSuchElementException("key: " + key)
 
+  def nil: V = null
+
   def applyOrNil(key: K): V = {
     val entry = lookup(key)
     if (entry == null || entry.value == null) null

src/main/scala/scala/reactive/container/RHashValMap.scala

@@ -26,6 +26,8 @@ class RHashValMap[@spec(Int, Long, Double) K, @spec(Int, Long, Double) V](
 
   init(emptyKey, emptyVal)
 
+  def nil: V = emptyVal.nil
+
   def inserts: Reactive[(K, V)] = insertsEmitter
   def removes: Reactive[(K, V)] = removesEmitter
 

src/main/scala/scala/reactive/container/RMap.scala

@@ -8,35 +8,98 @@ import scala.annotation.implicitNotFound
 
 
 
+/** A reactive map is a reactive counterpart of a mutable map.
+ *
+ *  Calling the `react` method of the `RMap` type returns.
+ *
+ *  @tparam K         the type of the keys in the reactive map
+ *  @tparam V         the type of the values in the reactive map
+ */
 trait RMap[@spec(Int, Long, Double) K, V <: AnyRef] extends RContainer[(K, V)] {
 
+  /** The special value that represents an absence of the value
+   *  under the specified key.
+   *
+   *  @returns        the nil value
+   */
+  def nil: V
+
+  /** Returns the value associated with the specified key or throws an exception if the key is not present.
+   *
+   *  @param k        the key
+   *  @returns        the value associated with the key
+   */
   def apply(k: K): V
 
+  /** Returns the value associated with the specified key or a nil value if the key is not present.
+   *
+   *  @param k        the key
+   *  @returns        the value associated with the key, or a nil value
+   */
+  def applyOrNil(k: K): V
+  
+  /** Optionally returns the value associated with the key, if it is present.
+   *
+   *  @param k        the key
+   *  @returns        the optional value associated with the key
+   */
+  def get(k: K): Option[V]
+
+  /** Returns the view over pairs in this map.
+   */
   def entries: PairContainer[K, V]
 
+  /** Returns the view over keys in this map.
+   */
   def keys: RContainer[K]
 
+  /** Returns the view over values in this map.
+   *
+   *  This method may only be used if the reactive map is injective,
+   *  that is, no two keys are mapped into the same value.
+   */
   def values: RContainer[V]
 
+  /** Returns the lifted view of the reactive map, used to obtain reactive values in this map.
+   */
   def react: RMap.Lifted[K, V]
 
 }
 
 
 object RMap {
 
+  /** Factory method for default reactive map creation.
+   */
   def apply[@spec(Int, Long, Double) K, V >: Null <: AnyRef](implicit can: RHashMap.Can[K, V]) = new RHashMap[K, V]
 
+  /** Reactive builder factory, automatically used for transforming containers into reactive maps.
+   */
   implicit def factory[@spec(Int, Long, Double) K, V >: Null <: AnyRef] = new RBuilder.Factory[(K, V), RMap[K, V]] {
     def apply() = RHashMap[K, V]
   }
 
+  /** Reactive pair builder factory, automatically used for transforming pair containers into reactive maps.
+   */
   implicit def pairFactory[@spec(Int, Long, Double) K, V >: Null <: AnyRef] = new PairBuilder.Factory[K, V, RMap[K, V]] {
     def apply() = RHashMap[K, V]
   }
 
+  /** Lifted view of the reactive map.
+   */
   trait Lifted[@spec(Int, Long, Double) K, V <: AnyRef] extends RContainer.Lifted[(K, V)] {
+    /** The original reactive map container.
+     */
     val container: RMap[K, V]
+
+    /** Returns the reactive value associated with the key.
+     *
+     *  The reactive value emits an event whenever a new value
+     *  is subsequently assigned to the specified key.
+     *
+     *  @param key         the key
+     *  @returns           the reactive containing all the values assigned to the key
+     */
     def apply(key: K): Reactive[V]
   }