Adding more ScalaDoc to dataflow api

akka-dataflow/src/main/scala/akka/dataflow/package.scala

@@ -43,10 +43,25 @@ package object dataflow {
   }
 
   implicit class DataflowPromise[T](val promise: Promise[T]) extends AnyVal {
+
+    /**
+     * Completes the Promise with the speicifed value or throws an exception if already
+     * completed. See Promise.success(value) for semantics.
+     *
+     * @param value The value which denotes the successful value of the Promise
+     * @return This Promise's Future
+     */
     final def <<(value: T): Future[T] @cps[Future[Any]] = shift {
       cont: (Future[T] ⇒ Future[Any]) ⇒ cont(promise.success(value).future)
     }
 
+    /**
+     * Completes this Promise with the value of the specified Future when/if it completes.
+     *
+     * @param other The Future whose value will be transfered to this Promise upon completion
+     * @param ec An ExecutionContext which will be used to execute callbacks registered in this method
+     * @return A Future representing the result of this operation
+     */
     final def <<(other: Future[T])(implicit ec: ExecutionContext): Future[T] @cps[Future[Any]] = shift {
       cont: (Future[T] ⇒ Future[Any]) ⇒
         val fr = Promise[Any]()
@@ -56,8 +71,21 @@ package object dataflow {
         fr.future
     }
 
+    /**
+     * Completes this Promise with the value of the specified Promise when/if it completes.
+     *
+     * @param other The Promise whose value will be transfered to this Promise upon completion
+     * @param ec An ExecutionContext which will be used to execute callbacks registered in this method
+     * @return A Future representing the result of this operation
+     */
     final def <<(other: Promise[T])(implicit ec: ExecutionContext): Future[T] @cps[Future[Any]] = <<(other.future)
 
+    /**
+     * For use only within a flow block or another compatible Delimited Continuations reset block.
+     *
+     * Returns the result of this Promise without blocking, by suspending execution and storing it as a
+     * continuation until the result is available.
+     */
     final def apply()(implicit ec: ExecutionContext): T @cps[Future[Any]] = shift(promise.future flatMap (_: T ⇒ Future[Any]))
   }