SI-8590 Expand doc comments for ExecutionContext

- link to Java API docs for ForkJoinPool-based default implementation
- add example for creating an execution context from a `java.util.concurrent.ExecutorService`
- add tags for parameters and return values
- expand doc comment for `prepare`

1 files changed, 60 insertions, 12 deletions

diff --git a/src/library/scala/concurrent/ExecutionContext.scala b/src/library/scala/concurrent/ExecutionContext.scala
index 4674c9174b..11d3bb8b02 100644
--- a/src/library/scala/concurrent/ExecutionContext.scala
+++ b/src/library/scala/concurrent/ExecutionContext.scala
@@ -61,28 +61,44 @@ or import scala.concurrent.ExecutionContext.Implicits.global.""")
 trait ExecutionContext {
 
   /** Runs a block of code on this execution context.
+   *
+   *  @param runnable  the task to execute
    */
   def execute(runnable: Runnable): Unit
 
   /** Reports that an asynchronous computation failed.
+   *
+   *  @param cause  the cause of the failure
    */
   def reportFailure(@deprecatedName('t) cause: Throwable): Unit
 
-  /** Prepares for the execution of a task. Returns the prepared
-   *  execution context. A valid implementation of `prepare` is one
-   *  that simply returns `this`.
+  /** Prepares for the execution of a task. Returns the prepared execution context.
+   *
+   *  `prepare` should be called at the site where an `ExecutionContext` is received (for
+   *  example, through an implicit method parameter). The returned execution context may
+   *  then be used to execute tasks. The role of `prepare` is to save any context relevant
+   *  to an execution's ''call site'', so that this context may be restored at the
+   *  ''execution site''. (These are often different: for example, execution may be
+   *  suspended through a `Promise`'s future until the `Promise` is completed, which may
+   *  be done in another thread, on another stack.)
+   *
+   *  Note: a valid implementation of `prepare` is one that simply returns `this`.
+   *
+   *  @return the prepared execution context
    */
   def prepare(): ExecutionContext = this
 
 }
 
 /**
- * An [[ExecutionContext]] that is also a Java [[Executor]].
+ * An [[ExecutionContext]] that is also a
+ * Java [[http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executor.html Executor]].
  */
 trait ExecutionContextExecutor extends ExecutionContext with Executor
 
 /**
- * An [[ExecutionContext]] that is also a Java [[ExecutorService]].
+ * An [[ExecutionContext]] that is also a
+ * Java [[http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html ExecutorService]].
  */
 trait ExecutionContextExecutorService extends ExecutionContextExecutor with ExecutorService
 
@@ -91,38 +107,70 @@ trait ExecutionContextExecutorService extends ExecutionContextExecutor with Exec
  */
 object ExecutionContext {
   /**
-   * This is the explicit global ExecutionContext,
-   * call this when you want to provide the global ExecutionContext explicitly
+   * The explicit global `ExecutionContext`. Invoke `global` when you want to provide the global
+   * `ExecutionContext` explicitly.
+   *
+   * The default `ExecutionContext` implementation is backed by a port of
+   * [[http://gee.cs.oswego.edu/dl/jsr166/dist/jsr166-4jdk7docs/java/util/concurrent/ForkJoinPool.html java.util.concurrent.ForkJoinPool]].
+   *
+   * @return the global `ExecutionContext`
    */
   def global: ExecutionContextExecutor = Implicits.global
 
   object Implicits {
     /**
-     * This is the implicit global ExecutionContext,
-     * import this when you want to provide the global ExecutionContext implicitly
+     * The implicit global `ExecutionContext`. Import `global` when you want to provide the global
+     * `ExecutionContext` implicitly.
+     *
+     * The default `ExecutionContext` implementation is backed by a port of
+     * [[http://gee.cs.oswego.edu/dl/jsr166/dist/jsr166-4jdk7docs/java/util/concurrent/ForkJoinPool.html java.util.concurrent.ForkJoinPool]].
      */
     implicit lazy val global: ExecutionContextExecutor = impl.ExecutionContextImpl.fromExecutor(null: Executor)
   }
 
   /** Creates an `ExecutionContext` from the given `ExecutorService`.
+   *
+   *  @param e         the `ExecutorService` to use
+   *  @param reporter  a function for error reporting
+   *  @return          the `ExecutionContext` using the given `ExecutorService`
    */
   def fromExecutorService(e: ExecutorService, reporter: Throwable => Unit): ExecutionContextExecutorService =
     impl.ExecutionContextImpl.fromExecutorService(e, reporter)
 
-  /** Creates an `ExecutionContext` from the given `ExecutorService` with the default Reporter.
+  /** Creates an `ExecutionContext` from the given `ExecutorService` with the [[scala.concurrent.ExecutionContext$.defaultReporter default reporter]].
+   *
+   *  If it is guaranteed that none of the executed tasks are blocking, a single-threaded `ExecutorService`
+   *  can be used to create an `ExecutionContext` as follows:
+   *
+   *  {{{
+   *  import java.util.concurrent.Executors
+   *  val ec = ExecutionContext.fromExecutorService(Executors.newSingleThreadExecutor())
+   *  }}}
+   *
+   *  @param e the `ExecutorService` to use
+   *  @return  the `ExecutionContext` using the given `ExecutorService`
    */
   def fromExecutorService(e: ExecutorService): ExecutionContextExecutorService = fromExecutorService(e, defaultReporter)
 
   /** Creates an `ExecutionContext` from the given `Executor`.
+   *
+   *  @param e         the `Executor` to use
+   *  @param reporter  a function for error reporting
+   *  @return          the `ExecutionContext` using the given `Executor`
    */
   def fromExecutor(e: Executor, reporter: Throwable => Unit): ExecutionContextExecutor =
     impl.ExecutionContextImpl.fromExecutor(e, reporter)
 
-  /** Creates an `ExecutionContext` from the given `Executor` with the default Reporter.
+  /** Creates an `ExecutionContext` from the given `Executor` with the [[scala.concurrent.ExecutionContext$.defaultReporter default reporter]].
+   *
+   *  @param e the `Executor` to use
+   *  @return  the `ExecutionContext` using the given `Executor`
    */
   def fromExecutor(e: Executor): ExecutionContextExecutor = fromExecutor(e, defaultReporter)
 
-  /** The default reporter simply prints the stack trace of the `Throwable` to System.err.
+  /** The default reporter simply prints the stack trace of the `Throwable` to [[http://docs.oracle.com/javase/8/docs/api/java/lang/System.html#err System.err]].
+   *
+   *  @return the function for error reporting
    */
   def defaultReporter: Throwable => Unit = _.printStackTrace()
 }