improve scaladoc

Author: samuelgruetter

language-adaptors/rxjava-scala/README.md

@@ -62,18 +62,12 @@ For more examples, see [RxScalaDemo.scala](https://github.com/Netflix/RxJava/blo
 
 Scala code using Rx should only import members from `rx.lang.scala` and below.
 
-Work on this adaptor is still in progress, and for the moment, the best source of documentation are the comments in the source code of [`rx.lang.scala.Observable`](https://github.com/Netflix/RxJava/blob/master/language-adaptors/rxjava-scala/src/main/scala/rx/lang/scala/Observable.scala).
-
 
 ## Documentation
 
-You can build the documentation as follows: In the RxJava root directory, run
-
-    ./gradlew :language-adaptors:rxjava-scala:scaladoc
-
-Then navigate to
+You can build the documentation by running `./gradlew scaladoc` in the RxJava root directory.
 
-    RxJava/language-adaptors/rxjava-scala/build/docs/scaladoc/index.html
+Then navigate to `RxJava/language-adaptors/rxjava-scala/build/docs/scaladoc/index.html` to display it.
 
 
 ## Binaries

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

@@ -384,19 +384,31 @@ class RxScalaDemo extends JUnitSuite {
     }
   }
 
-  @Test def materializeExample() {
+  @Test def materializeExample1() {
     def printObservable[T](o: Observable[T]): Unit = {
       import Notification._
-      for (n <- o.materialize.toBlockingObservable) n match {
+      o.materialize.subscribe(n => n match {
         case OnNext(v) => println("Got value " + v)
         case OnCompleted() => println("Completed")
         case OnError(err) => println("Error: " + err.getMessage)
-      }
+      })
     }
+    
     val o1 = Observable.interval(100 millis).take(3)
-    val o2 = o1 ++ Observable(new IOException("Oops"))
+    val o2 = Observable(new IOException("Oops"))
     printObservable(o1)
+    waitFor(o1)
     printObservable(o2)
+    waitFor(o2)
+  }
+  
+  @Test def materializeExample2() {
+    import Notification._
+    Observable(1, 2, 3).materialize.subscribe(n => n match {
+      case OnNext(v) => println("Got value " + v)
+      case OnCompleted() => println("Completed")
+      case OnError(err) => println("Error: " + err.getMessage)
+    })
   }
 
   def output(s: String): Unit = println(s)

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

@@ -19,10 +19,10 @@ import java.{ lang => jlang }
 import rx.util.functions._
 
 /**
- * These function conversions convert between Scala functions and Rx Funcs and Actions.
- * Most users RxScala won't need them, but they might be useful if one wants to use
- * the rx.Observable directly instead of using rx.lang.scala.Observable or if one wants
- * to use a Java library taking/returning Funcs and Actions.
+ * These function conversions convert between Scala functions and Rx `Func`s and `Action`s.
+ * Most RxScala users won't need them, but they might be useful if one wants to use
+ * the `rx.Observable` directly instead of using `rx.lang.scala.Observable` or if one wants
+ * to use a Java library taking/returning `Func`s and `Action`s.
  */
 object ImplicitFunctionConversions {
   import language.implicitConversions

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

@@ -1,9 +1,25 @@
 package rx.lang.scala
 
+/**
+ * Emitted by Observables returned by [[rx.lang.scala.Observable.materialize]].
+ */
 sealed trait Notification[+T] {
   def asJava: rx.Notification[_ <: T]
 }
 
+/**
+ * Provides pattern matching support for Notifications.
+ * 
+ * Example:
+ * {{{
+ * import Notification._
+ * Observable(1, 2, 3).materialize.subscribe(n => n match {
+ *   case OnNext(v) => println("Got value " + v)
+ *   case OnCompleted() => println("Completed")
+ *   case OnError(err) => println("Error: " + err.getMessage)
+ * })
+ * }}}
+ */
 object Notification {
 
   def apply[T](n: rx.Notification[_ <: T]): Notification[T] = n.getKind match {

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

@@ -20,7 +20,7 @@ package rx.lang.scala
 /**
  * The Observable interface that implements the Reactive Pattern.
  */
-class Observable[+T](val asJava: rx.Observable[_ <: T])
+class Observable[+T] private[scala] (val asJava: rx.Observable[_ <: T])
   // Uncommenting this line combined with `new Observable(...)` instead of `new Observable[T](...)`
   // makes the compiler crash
   extends AnyVal 
@@ -641,7 +641,8 @@ class Observable[+T](val asJava: rx.Observable[_ <: T])
   } 
 
   /**
-   * <p>
+   * Returns an Observable which only emits those items for which a given predicate holds.
+   * 
    * <img width="640" src="https://raw.github.com/wiki/Netflix/RxJava/images/rx-operators/filter.png">
    * 
    * @param predicate
@@ -1278,7 +1279,7 @@ class Observable[+T](val asJava: rx.Observable[_ <: T])
    * @param that
    *            an Observable to be merged
    * @return an Observable that emits items that are the result of flattening the items emitted by
-   *         {$code this} and {$code that}
+   *         {@code this} and {@code that}
    */
   def mergeDelayError[U >: T](that: Observable[U]): Observable[U] = {
     Observable[U](rx.Observable.mergeDelayError[U](this.asJava, that.asJava))
@@ -1761,6 +1762,9 @@ class Observable[+T](val asJava: rx.Observable[_ <: T])
 
 }
 
+/**
+ * Provides various ways to construct new Observables.
+ */
 object Observable {
   import scala.collection.JavaConverters._
   import scala.collection.immutable.Range
@@ -1982,7 +1986,7 @@ object Observable {
 // Cannot yet have inner class because of this error message: 
 // "implementation restriction: nested class is not allowed in value class.
 // This restriction is planned to be removed in subsequent releases."  
-class WithFilter[+T] private[scala] (p: T => Boolean, asJava: rx.Observable[_ <: T]) {
+private[scala] class WithFilter[+T] (p: T => Boolean, asJava: rx.Observable[_ <: T]) {
   import rx.lang.scala.ImplicitFunctionConversions._
 
   def map[B](f: T => B): Observable[B] = {
@@ -2000,7 +2004,7 @@ class WithFilter[+T] private[scala] (p: T => Boolean, asJava: rx.Observable[_ <:
   // there is no foreach here, that's only available on BlockingObservable
 }
 
-class UnitTestSuite extends org.scalatest.junit.JUnitSuite {
+private[scala] class UnitTestSuite extends org.scalatest.junit.JUnitSuite {
   import scala.concurrent.duration._
   import org.junit.{Before, Test, Ignore}
   import org.junit.Assert._

language-adaptors/rxjava-scala/src/main/scala/rx/lang/scala/concurrency/Schedulers.scala

@@ -25,21 +25,21 @@ object Schedulers {
   def newThread: Scheduler = rx.concurrency.Schedulers.newThread
 
   /**
-   * Returns a [[rx.lang.scala.Scheduler]] that queues work on an [[java.util.concurrent.Executor]].
+   * Returns a [[rx.lang.scala.Scheduler]] that queues work on an `java.util.concurrent.Executor`.
    * 
    * Note that this does not support scheduled actions with a delay.
    */
   def executor(executor: Executor): Scheduler = rx.concurrency.Schedulers.executor(executor)
 
   /**
-   * Returns a [[rx.lang.scala.Scheduler]] that queues work on an [[java.util.concurrent.ScheduledExecutorService]].
+   * Returns a [[rx.lang.scala.Scheduler]] that queues work on an `java.util.concurrent.ScheduledExecutorService`.
    */
   def executor(executor: ScheduledExecutorService): Scheduler = rx.concurrency.Schedulers.executor(executor)
 
   /**
    * Returns a [[rx.lang.scala.Scheduler]] intended for computational work.
    * 
-   * The implementation is backed by a [[java.util.concurrent.ScheduledExecutorService]] thread-pool sized to the number of CPU cores.
+   * The implementation is backed by a `java.util.concurrent.ScheduledExecutorService` thread-pool sized to the number of CPU cores.
    *
    * This can be used for event-loops, processing callbacks and other computational work.
    * 
@@ -50,7 +50,7 @@ object Schedulers {
   /**
    * [[rx.lang.scala.Scheduler]] intended for IO-bound work.
    * 
-   * The implementation is backed by an [[java.util.concurrent.Executor]] thread-pool that will grow as needed.
+   * The implementation is backed by an `java.util.concurrent.Executor` thread-pool that will grow as needed.
    * 
    * This can be used for asynchronously performing blocking IO.
    * 

language-adaptors/rxjava-scala/src/main/scala/rx/lang/scala/concurrency/package.scala

@@ -17,6 +17,9 @@ package rx.lang.scala
 
 import rx.concurrency.CurrentThreadScheduler
 
+/**
+ * Provides schedulers.
+ */
 package object concurrency {
   // These classes are not exposed to Scala users, but are accessible through
   // rx.lang.scala.concurrency.Schedulers:

language-adaptors/rxjava-scala/src/main/scala/rx/lang/scala/observables/BlockingObservable.scala

@@ -23,7 +23,7 @@ import rx.lang.scala.ImplicitFunctionConversions._
  * 
  * You can obtain a BlockingObservable from an Observable using [[Observable.toBlockingObservable]]
  */
-class BlockingObservable[+T](val asJava: rx.observables.BlockingObservable[_ <: T]) 
+class BlockingObservable[+T] private[scala] (val asJava: rx.observables.BlockingObservable[_ <: T]) 
   extends AnyVal 
 {
 
@@ -131,7 +131,7 @@ class BlockingObservable[+T](val asJava: rx.observables.BlockingObservable[_ <:
 // Cannot yet have inner class because of this error message: 
 // "implementation restriction: nested class is not allowed in value class.
 // This restriction is planned to be removed in subsequent releases."  
-class WithFilter[+T] private[observables] (p: T => Boolean, asJava: rx.observables.BlockingObservable[_ <: T]) {
+private[observables] class WithFilter[+T] (p: T => Boolean, asJava: rx.observables.BlockingObservable[_ <: T]) {
   import rx.lang.scala.ImplicitFunctionConversions._
 
   // there's no map and flatMap here, they're only available on Observable

language-adaptors/rxjava-scala/src/main/scala/rx/lang/scala/observables/package.scala

@@ -4,9 +4,9 @@ package rx.lang.scala
  * Contains special Observables.
  * 
  * In Scala, this package only contains [[rx.lang.scala.observables.BlockingObservable]].
- * In the corresponding Java package {{{rx.observables}}}, there is also a
- * {{{GroupedObservable}}} and a {{{ConnectableObservable}}}, but these are not needed
- * in Scala, because we use a pair {{{(key, observable)}}} instead of {{{GroupedObservable}}}
- * and a pair {{{(startFunction, observable)}}} instead of {{{ConnectableObservable}}}. 
+ * In the corresponding Java package `rx.observables`, there is also a
+ * `GroupedObservable` and a `ConnectableObservable`, but these are not needed
+ * in Scala, because we use a pair `(key, observable)` instead of `GroupedObservable`
+ * and a pair `(startFunction, observable)` instead of `ConnectableObservable`. 
  */
 package object observables {}

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

@@ -15,17 +15,22 @@
  */
 package rx.lang
 
+import java.util.concurrent.TimeUnit
+import java.util.Date
 
-/**
- * This object contains aliases to all types Scala users need to import.
- * 
+/* 
  * Note that:
- * -  Scala users cannot use Java's type with variance without always using writing
+ * -  Scala users cannot use Java's types with variance without always using writing
  *    e.g. rx.Notification[_ <: T], so we create aliases fixing the variance
- * -  For consistency, we create aliases for all types
+ * -  For consistency, we create aliases for all types which Scala users need
+ */
+
+/**
+ * This package contains all classes that RxScala users need.
+ * 
+ * It mirrors the structure of package `rx`, but implementation classes that RxScala users
+ * will not need are left out.
  */
-import java.util.concurrent.TimeUnit
-import java.util.Date
 package object scala {
 
   /*
@@ -45,23 +50,23 @@ package object scala {
   /**
    * Provides a mechanism for receiving push-based notifications.
    *
-   * After an Observer calls an [[rx.lang.scala.Observable]]'s {{{subscribe}}} method, the Observable
-   * calls the Observer's {{{onNext}}} method to provide notifications. A well-behaved Observable will
-   * call an Observer's {{{onCompleted}}} method exactly once or the Observer's {{{onError}}} method exactly once.
+   * After an Observer calls an [[rx.lang.scala.Observable]]'s `subscribe` method, the Observable
+   * calls the Observer's `onNext` method to provide notifications. A well-behaved Observable will
+   * call an Observer's `onCompleted` method exactly once or the Observer's `onError` method exactly once.
    */
   trait Observer[-T] {
 
     /**
      * Notifies the Observer that the [[rx.lang.scala.Observable]] has finished sending push-based notifications.
      *
-     * The [[rx.lang.scala.Observable]] will not call this method if it calls {{{onError}}}.
+     * The [[rx.lang.scala.Observable]] will not call this method if it calls `onError`.
      */
     def onCompleted(): Unit
 
     /**
      * Notifies the Observer that the [[rx.lang.scala.Observable]] has experienced an error condition.
      *
-     * If the [[rx.lang.scala.Observable]] calls this method, it will not thereafter call {{{onNext}}} or {{{onCompleted}}}.
+     * If the [[rx.lang.scala.Observable]] calls this method, it will not thereafter call `onNext` or `onCompleted`.
      */
     def onError(e: Throwable): Unit
 
@@ -70,7 +75,7 @@ package object scala {
      *
      * The [[rx.lang.scala.Observable]] calls this closure 0 or more times.
      *
-     * The [[rx.lang.scala.Observable]] will not call this method again after it calls either {{{onCompleted}}} or {{{onError}}}.
+     * The [[rx.lang.scala.Observable]] will not call this method again after it calls either `onCompleted` or `onError`.
      */
     def onNext(arg: T): Unit
   }
@@ -201,6 +206,8 @@ package object scala {
     def unsubscribe(): Unit
   }
   
+  import language.implicitConversions
+  
   private[scala] implicit def fakeSubscription2RxSubscription(s: Subscription): rx.Subscription = 
     new rx.Subscription {
       def unsubscribe() = s.unsubscribe()