Merge pull request #13 from typesafehub/wip-genjavadoc

add genjavadoc and fix doc comments

build.sbt

@@ -11,3 +11,4 @@ scalaVersion := "2.10.3"
 lazy val spi = project
 
 lazy val tck = project.dependsOn(spi)
+

project/Build.scala

@@ -0,0 +1,17 @@
+import sbt._
+import Keys._
+
+object Common {
+  lazy val JavaDoc = config("genjavadoc") extend Compile
+
+  val javadocSettings = inConfig(JavaDoc)(Defaults.configSettings) ++ Seq(
+      packageDoc in Compile <<= packageDoc in JavaDoc,
+        sources in JavaDoc <<= (target, compile in Compile, sources in Compile) map ((t, c, s) =>
+              (t / "java" ** "*.java").get ++ s.filter(_.getName.endsWith(".java"))
+    ),
+    javacOptions in JavaDoc := Seq(),
+      artifactName in packageDoc in JavaDoc := ((sv, mod, art) => "" + mod.name + "_" + sv.binary + "-" + mod.revision + "-javadoc.jar"),
+        libraryDependencies += compilerPlugin("com.typesafe.genjavadoc" %% "genjavadoc-plugin" % "0.5" cross CrossVersion.full),
+          scalacOptions in Compile <+= target map (t => "-P:genjavadoc:out=" + (t / "java"))
+  )
+}

spi/build.sbt

@@ -1,3 +1,5 @@
 organization := "org.reactivestreams"
 
 name := "reactive-streams-spi"
+
+Common.javadocSettings

spi/src/main/scala/org/reactivestreams/api/Producer.scala

@@ -3,7 +3,7 @@ package api
 
 /**
  * A Producer is the logical source of elements of a given type. 
- * The underlying implementation is done by way of a [[asyncrx.spi.Publisher]].
+ * The underlying implementation is done by way of a [[org.reactivestreams.spi.Publisher]].
  * This interface is the user-level API for a source while a Publisher is the
  * SPI.
  * 
@@ -15,6 +15,8 @@ trait Producer[T] {
   /**
    * Get the underlying Publisher for this Producer. This method should only be used by
    * implementations of this API.
+   * 
+   * @return the underlying publisher for this producer
    */
   def getPublisher: spi.Publisher[T]
 
@@ -24,19 +26,20 @@ trait Producer[T] {
    * underlying Publisher, which will initiate the transfer of the produced
    * stream of elements from producer to consumer until either of three things
    * happen:
-   * 
    * <ul>
    * <li>The stream ends normally (no more elements available).</li>
    * <li>The producer encounters a fatal error condition.</li>
    * <li>The consumer cancels the reception of more elements.</li>
    * </ul>
+   * 
+   * @param consumer The consumer to register with this producer.
    */
   def produceTo(consumer: Consumer[T]): Unit
 }
 
 /**
  * A Consumer is the logical sink of elements of a given type.
- * The underlying implementation is done by way of a [[asyncrx.spi.Subscriber]].
+ * The underlying implementation is done by way of a [[org.reactivestreams.spi.Subscriber]].
  * This interface is the user-level API for a sink while a Subscriber is the SPI.
  * 
  * Implementations of this interface will typically offer domain- or language-specific
@@ -47,6 +50,8 @@ trait Consumer[T] {
   /**
    * Get the underlying Subscriber for this Consumer. This method should only be used by
    * implementations of this API.
+   * 
+   * @return the underlying subscriber for this consumer
    */
   def getSubscriber: spi.Subscriber[T]
 }

spi/src/main/scala/org/reactivestreams/spi/Publisher.scala

@@ -20,6 +20,8 @@ trait Subscription {
    * The number of requested elements is cumulative to the number requested previously.
    * The Publisher may eventually publish up to the requested number of elements to
    * the [[Subscriber]] which owns this Subscription.
+   * 
+   * @param elements The number of elements requested.
    */
   def requestMore(elements: Int): Unit
 }
@@ -34,6 +36,8 @@ trait Publisher[T] {
   /**
    * Subscribe the given [[Subscriber]] to this Publisher. A Subscriber can at most be subscribed once
    * to a given Publisher, and to at most one Publisher in total.
+   * 
+   * @param subscriber The subscriber to register with this publisher.
    */
   def subscribe(subscriber: Subscriber[T]): Unit
 }
@@ -49,13 +53,17 @@ trait Subscriber[T] {
    * The [[Publisher]] generates a [[Subscription]] upon [[Publisher#subscribe]] and passes
    * it on to the Subscriber named there using this method. The Publisher may choose to reject
    * the subscription request by calling [[#onError]] instead.
+   * 
+   * @param subscription The subscription which connects this subscriber to its publisher.
    */
   def onSubscribe(subscription: Subscription): Unit
 
   /**
    * The [[Publisher]] calls this method to pass one element to this Subscriber. The element
    * must not be <code>null</code>. The Publisher must not call this method more often than
    * the Subscriber has signaled demand for via the corresponding [[Subscription]].
+   * 
+   * @param element The element that is passed from publisher to subscriber.
    */
   def onNext(element: T): Unit
 
@@ -75,6 +83,8 @@ trait Subscriber[T] {
    * This method is not intended to pass validation errors or similar from Publisher to Subscriber
    * in order to initiate an orderly shutdown of the exchange; it is intended only for fatal
    * failure conditions which make it impossible to continue processing further elements.
+   * 
+   * @param cause An exception which describes the reason for tearing down this stream.
    */
   def onError(cause: Throwable): Unit
 }