From 0e941d764601a245a758ca1fcbdc216006d3ddfd Mon Sep 17 00:00:00 2001
From: Viktor Klang <viktor.klang@gmail.com>
Date: Fri, 30 Dec 2011 18:11:32 +0100
Subject: [PATCH] Adding some more ScalaDoc to Future to explain foreach,
 withFilter and filter

---
 akka-actor/src/main/scala/akka/dispatch/Future.scala | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/akka-actor/src/main/scala/akka/dispatch/Future.scala b/akka-actor/src/main/scala/akka/dispatch/Future.scala
index 76de3d07c3..47c91a9cda 100644
--- a/akka-actor/src/main/scala/akka/dispatch/Future.scala
+++ b/akka-actor/src/main/scala/akka/dispatch/Future.scala
@@ -527,11 +527,17 @@ sealed trait Future[+T] extends japi.Future[T] with Await.Awaitable[T] {
     p
   }
 
+  /**
+   * Same as onSuccess { case r => f(r) } but is also used in for-comprehensions
+   */
   final def foreach(f: T ⇒ Unit): Unit = onComplete {
     case Right(r) ⇒ f(r)
     case _        ⇒
   }
 
+  /**
+   * Used by for-comprehensions
+   */
   final def withFilter(p: T ⇒ Boolean) = new FutureWithFilter[T](this, p)
 
   final class FutureWithFilter[+A](self: Future[A], p: A ⇒ Boolean) {
@@ -541,6 +547,11 @@ sealed trait Future[+T] extends japi.Future[T] with Await.Awaitable[T] {
     def withFilter(q: A ⇒ Boolean): FutureWithFilter[A] = new FutureWithFilter[A](self, x ⇒ p(x) && q(x))
   }
 
+  /**
+   * Returns a new Future that will hold the successful result of this Future if it matches
+   * the given predicate, if it doesn't match, the resulting Future will be a failed Future
+   * with a MatchError, of if this Future fails, that failure will be propagated to the returned Future
+   */
   final def filter(pred: T ⇒ Boolean): Future[T] = {
     val p = Promise[T]()
     onComplete {