Update docs for "apply" and add an example

Author: zsxwing

language-adaptors/rxjava-scala/src/examples/scala/rx/lang/scala/examples/RxScalaDemo.scala

@@ -620,6 +620,34 @@ class RxScalaDemo extends JUnitSuite {
     o.take(1).subscribe(println(_))
   }
 
+  @Test def createExampleGood2() {
+    import scala.io.{Codec, Source}
+
+    val rxscala = Observable[String](subscriber => {
+      try {
+        val input = new java.net.URL("http://rxscala.github.io/").openStream()
+        subscriber.add(Subscription {
+          input.close()
+        })
+        Source.fromInputStream(input)(Codec.UTF8).getLines()
+          .takeWhile(_ => !subscriber.isUnsubscribed)
+          .foreach(subscriber.onNext(_))
+        if (!subscriber.isUnsubscribed) {
+          subscriber.onCompleted()
+        }
+      }
+      catch {
+        case e: Throwable => if (!subscriber.isUnsubscribed) subscriber.onError(e)
+      }
+    }).subscribeOn(IOScheduler())
+
+    val count = rxscala.flatMap(_.split("\\W+").toSeq.toObservable)
+      .map(_.toLowerCase)
+      .filter(_ == "rxscala")
+      .size
+    println(s"RxScala appears ${count.toBlockingObservable.single} times in http://rxscala.github.io/")
+  }
+
   def output(s: String): Unit = println(s)
 
   /** Subscribes to obs and waits until obs has completed. Note that if you subscribe to

language-adaptors/rxjava-scala/src/main/scala/rx/lang/scala/Observable.scala

@@ -3330,10 +3330,19 @@ object Observable {
    * Write the function you pass so that it behaves as an Observable: It should invoke the
    * Subscriber's `onNext`, `onError`, and `onCompleted` methods appropriately.
    *
+   * You can `add` custom [[Subscription]]s to [[Subscriber]]. These [[Subscription]]s will be called
+   * <ul>
+   *   <li>when someone calls `unsubscribe`.</li>
+   *   <li>after `onCompleted` or `onError`.</li>
+   * </ul>
+   *
    * See <a href="http://go.microsoft.com/fwlink/?LinkID=205219">Rx Design Guidelines (PDF)</a> for detailed
    * information.
    *
-   * @tparam T
+   * See `<a href="https://github.com/Netflix/RxJava/blob/master/language-adaptors/rxjava-scala/src/examples/scala/rx/lang/scala/examples/RxScalaDemo.scala">RxScalaDemo</a>.createExampleGood`
+   * and `<a href="https://github.com/Netflix/RxJava/blob/master/language-adaptors/rxjava-scala/src/examples/scala/rx/lang/scala/examples/RxScalaDemo.scala">RxScalaDemo</a>.createExampleGood2`.
+   *
+   * @param T
    *            the type of the items that this Observable emits
    * @param f
    *            a function that accepts a `Subscriber[T]`, and invokes its `onNext`,