Adding some comments to block on. Removing timeout parameters.

4 files changed, 31 insertions, 9 deletions

diff --git a/src/library/scala/concurrent/ExecutionContext.scala b/src/library/scala/concurrent/ExecutionContext.scala
index 5ab712b89a..4a3e112c1a 100644
--- a/src/library/scala/concurrent/ExecutionContext.scala
+++ b/src/library/scala/concurrent/ExecutionContext.scala
@@ -24,6 +24,7 @@ trait ExecutionContext {
 trait Task[T] {
   
   def start(): Unit
+  
   def future: Future[T]
   
 }
diff --git a/src/library/scala/concurrent/Future.scala b/src/library/scala/concurrent/Future.scala
index 361bed4d2b..2393efcef6 100644
--- a/src/library/scala/concurrent/Future.scala
+++ b/src/library/scala/concurrent/Future.scala
@@ -30,8 +30,6 @@ import java.util.concurrent.atomic.{ AtomicReferenceFieldUpdater, AtomicInteger,
  *  The timeout of the future is:
  *  - if this future was obtained from a task (i.e. by calling `task.future`), the timeout associated with that task
  *  - if this future was obtained from a promise (i.e. by calling `promise.future`), the timeout associated with that promise
- *  - if this future was obtained from a combinator on some other future `g` (e.g. by calling `g.map(_)`), the timeout of `g`
- *  - if this future was obtained from a combinator on multiple futures `g0`, ..., `g1`, the minimum of the timeouts of these futures
  *
  *  @define multipleCallbacks
  *  Multiple callbacks may be registered; there is no guarantee that they will be
@@ -189,7 +187,7 @@ self =>
    *  future (6 / 2) recover { case e: ArithmeticException ⇒ 0 } // result: 3
    *  }}}
    */
-  def recover[U >: T](pf: PartialFunction[Throwable, U])(implicit timeout: Timeout): Future[U] = {
+  def recover[U >: T](pf: PartialFunction[Throwable, U]): Future[U] = {
     val p = newPromise[U]
     
     onComplete {
@@ -214,7 +212,7 @@ self =>
    *  
    *  $forComprehensionExample
    */
-  def map[S](f: T => S)(implicit timeout: Timeout): Future[S] = {
+  def map[S](f: T => S): Future[S] = {
     val p = newPromise[S]
     
     onComplete {
@@ -232,7 +230,7 @@ self =>
    *  
    *  $forComprehensionExample
    */
-  def flatMap[S](f: T => Future[S])(implicit timeout: Timeout): Future[S] = {
+  def flatMap[S](f: T => Future[S]): Future[S] = {
     val p = newPromise[S]
     
     onComplete {
@@ -261,7 +259,7 @@ self =>
    *  block on h // throw a NoSuchElementException
    *  }}}
    */
-  def filter(p: T => Boolean)(implicit timeout: Timeout): Future[T] = {
+  def filter(p: T => Boolean): Future[T] = {
     val p = newPromise[T]
     
     onComplete {
@@ -281,7 +279,6 @@ self =>
  *  
  *  Each timeout exception contains an origin future which originally timed out.
  */
-class TimeoutException(origin: Future[T], message: String, cause: Throwable = null) extends Exception(message, cause) {
-  def this(origin: Future[T], message: String) = this(origin, message, null)
+class TimeoutException(origin: Future[T], message: String) extends java.util.concurrent.TimeoutException(message) {
   def this(origin: Future[T]) = this(origin, "Future timed out.")
 }
diff --git a/src/library/scala/concurrent/Promise.scala b/src/library/scala/concurrent/Promise.scala
index 4c6b11dfd6..c5336ab00f 100644
--- a/src/library/scala/concurrent/Promise.scala
+++ b/src/library/scala/concurrent/Promise.scala
@@ -16,11 +16,14 @@ package scala.concurrent
  *  A promise is assigned a timeout when created. After the timeout expires,
  *  the promise will be failed with a TimeoutException.
  *
- *  @promiseCompletion
+ *  @define promiseCompletion
  *  If the promise has already been fulfilled, failed or has timed out,
  *  calling this method will throw an IllegalStateException.
  */
 trait Promise[T] {
+  
+  /** Future containing the value of this promise.
+   */
   def future: Future[T]
   
   /** Completes the promise with a value.
diff --git a/src/library/scala/concurrent/package.scala b/src/library/scala/concurrent/package.scala
index 64ccdeb0ab..74e8b71eff 100644
--- a/src/library/scala/concurrent/package.scala
+++ b/src/library/scala/concurrent/package.scala
@@ -23,11 +23,32 @@ package object concurrent {
     override protected def initialValue = null
   }
   
+  /** The keyword used to block on a piece of code which potentially blocks.
+   *
+   *  @define mayThrow
+   *  Calling this method may throw the following exceptions:
+   *  - CancellationException - if the computation was cancelled
+   *  - InterruptedException - in the case that a wait within the blockable object was interrupted
+   *  - TimeoutException - in the case that the blockable object timed out
+   */
   object block {
+    
+    /** Blocks on a piece of code.
+     *  
+     *  @param body         A piece of code which contains potentially blocking or long running calls.
+     *  
+     *  $mayThrow
+     */
     def on[T](body: =>T): T = on(new Blockable[T] {
       def block()(implicit cb: CanBlock) = body
     })
     
+    /** Blocks on a blockable object.
+     *  
+     *  @param blockable    An object with a `block` method which runs potentially blocking or long running calls.
+     *  
+     *  $mayThrow
+     */
     def on[T](blockable: Blockable[T]): T = {
       currentExecutionContext.get match {
         case null => blockable.block()(null) // outside