From 4d6e90e6c88cd8d4b60a4441dc0297fd3685b683 Mon Sep 17 00:00:00 2001
From: Viktor Klang <viktor.klang@gmail.com>
Date: Sun, 12 Aug 2012 18:40:05 +0200
Subject: [PATCH] Adding more ScalaDoc to dataflow api

---
 .../main/scala/akka/dataflow/package.scala    | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/akka-dataflow/src/main/scala/akka/dataflow/package.scala b/akka-dataflow/src/main/scala/akka/dataflow/package.scala
index 27b7ba2275..bdf1d79aa2 100644
--- a/akka-dataflow/src/main/scala/akka/dataflow/package.scala
+++ b/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]))
   }