From 71d2db0552b840aa133e8ed4d51d59364432dbbb Mon Sep 17 00:00:00 2001
From: Patrik Nordwall <patrik.nordwall@gmail.com>
Date: Fri, 6 Mar 2015 10:23:26 +0100
Subject: [PATCH] =str Fix some scaladoc

---
 .../akka/stream/impl/GenJunctions.scala.template   |  4 ++--
 .../akka/stream/javadsl/SinkCreate.scala.template  |  8 ++++----
 akka-stream/src/main/scala/akka/stream/Shape.scala |  2 +-
 .../stream/impl/ActorFlowMaterializerImpl.scala    | 14 +++++++-------
 .../src/main/scala/akka/stream/impl/Sinks.scala    |  8 --------
 .../src/main/scala/akka/stream/impl/Sources.scala  |  4 ----
 .../stream/impl/StreamSubscriptionTimeout.scala    |  8 ++++++--
 .../scala/akka/stream/javadsl/FlexiMerge.scala     |  4 ++--
 .../scala/akka/stream/javadsl/FlexiRoute.scala     |  5 ++---
 .../src/main/scala/akka/stream/javadsl/Flow.scala  |  2 +-
 .../src/main/scala/akka/stream/javadsl/Graph.scala |  4 ++--
 .../main/scala/akka/stream/javadsl/StreamTcp.scala | 10 ++++------
 .../src/main/scala/akka/stream/scaladsl/Flow.scala |  4 ++--
 .../stream/scaladsl/ImplicitFlowMaterializer.scala |  4 ++--
 .../src/main/scala/akka/stream/scaladsl/Sink.scala |  2 +-
 .../src/main/scala/akka/stream/stage/Stage.scala   |  2 +-
 16 files changed, 37 insertions(+), 48 deletions(-)

diff --git a/akka-stream/src/main/boilerplate/akka/stream/impl/GenJunctions.scala.template b/akka-stream/src/main/boilerplate/akka/stream/impl/GenJunctions.scala.template
index 9c70808a9b..839e50f7c4 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/impl/GenJunctions.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/impl/GenJunctions.scala.template
@@ -10,8 +10,8 @@ import akka.stream.impl.StreamLayout.Module
 import akka.stream.scaladsl.OperationAttributes
 import akka.stream.scaladsl.OperationAttributes._
 
-/** Boilerplate generated Junctions */
-object GenJunctions {
+/** INTERNAL API: Boilerplate generated Junctions */
+private[akka] object GenJunctions {
 
   sealed trait ZipWithModule {
     /** Allows hiding the boilerplate Props creation from the materializer */
diff --git a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
index a2bc543997..b699ab7a79 100644
--- a/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
+++ b/akka-stream/src/main/boilerplate/akka/stream/javadsl/SinkCreate.scala.template
@@ -10,15 +10,15 @@ import akka.stream.scaladsl.JavaConverters._
 trait SinkCreate {
 
   /**
-   * Creates a `Sink` by using a FlowGraphBuilder from this [[PartialFlowGraph]] on a block that expects
-   * a [[FlowGraphBuilder]] and returns the `UndefinedSource`.
+   * Creates a `Sink` by using a `FlowGraph.Builder` on a block that expects
+   * a [[FlowGraph.Builder]] and returns the `UndefinedSource`.
    */
   def create[T](block: japi.Function[FlowGraph.Builder, Inlet[T]]): Sink[T, Unit] =
     new Sink(scaladsl.Sink() { b ⇒ block.apply(b.asJava) })
 
   /**
-   * Creates a `Sink` by using a FlowGraphBuilder from this [[PartialFlowGraph]] on a block that expects
-   * a [[FlowGraphBuilder]] and returns the `UndefinedSource`.
+   * Creates a `Sink` by using a `FlowGraph.Builder` on a block that expects
+   * a [[FlowGraph.Builder]] and returns the `UndefinedSource`.
    */
   def create[T, S <: Shape, M](g1: Graph[S, M], block: japi.Function2[FlowGraph.Builder, S, Inlet[T]]): Sink[T, M] =
     new Sink(scaladsl.Sink(g1) { b ⇒ s => block.apply(b.asJava, s) })
diff --git a/akka-stream/src/main/scala/akka/stream/Shape.scala b/akka-stream/src/main/scala/akka/stream/Shape.scala
index 6e82fb4f1e..ed62bc9ca4 100644
--- a/akka-stream/src/main/scala/akka/stream/Shape.scala
+++ b/akka-stream/src/main/scala/akka/stream/Shape.scala
@@ -70,7 +70,7 @@ abstract class Shape {
   def requireSamePortsAs(s: Shape): Unit = require(hasSamePortsAs(s), nonCorrespondingMessage(s))
 
   /**
-   * Asserting version of [[#hasSameShapeAs]].
+   * Asserting version of [[#hasSamePortsAndShapeAs]].
    */
   def requireSamePortsAndShapeAs(s: Shape): Unit = require(hasSamePortsAndShapeAs(s), nonCorrespondingMessage(s))
 
diff --git a/akka-stream/src/main/scala/akka/stream/impl/ActorFlowMaterializerImpl.scala b/akka-stream/src/main/scala/akka/stream/impl/ActorFlowMaterializerImpl.scala
index 08bae18a57..3725eb5844 100644
--- a/akka-stream/src/main/scala/akka/stream/impl/ActorFlowMaterializerImpl.scala
+++ b/akka-stream/src/main/scala/akka/stream/impl/ActorFlowMaterializerImpl.scala
@@ -33,12 +33,12 @@ object ActorFlowMaterializerImpl {
 /**
  * INTERNAL API
  */
-case class ActorFlowMaterializerImpl(override val settings: ActorFlowMaterializerSettings,
-                                     dispatchers: Dispatchers,
-                                     supervisor: ActorRef,
-                                     flowNameCounter: AtomicLong,
-                                     namePrefix: String,
-                                     optimizations: Optimizations)
+private[akka] case class ActorFlowMaterializerImpl(override val settings: ActorFlowMaterializerSettings,
+                                                   dispatchers: Dispatchers,
+                                                   supervisor: ActorRef,
+                                                   flowNameCounter: AtomicLong,
+                                                   namePrefix: String,
+                                                   optimizations: Optimizations)
   extends ActorFlowMaterializer {
   import ActorFlowMaterializerImpl._
   import akka.stream.impl.Stages._
@@ -274,4 +274,4 @@ private[akka] object ActorProcessorFactory {
     impl ! ExposedPublisher(p.asInstanceOf[ActorPublisher[Any]])
     p
   }
-}
\ No newline at end of file
+}
diff --git a/akka-stream/src/main/scala/akka/stream/impl/Sinks.scala b/akka-stream/src/main/scala/akka/stream/impl/Sinks.scala
index 4e7eb40b7b..f8f238001a 100644
--- a/akka-stream/src/main/scala/akka/stream/impl/Sinks.scala
+++ b/akka-stream/src/main/scala/akka/stream/impl/Sinks.scala
@@ -43,10 +43,6 @@ class PublisherSink[In](val attributes: OperationAttributes, shape: SinkShape[In
 
   override def toString: String = "PublisherSink"
 
-  /**
-   * This method is only used for Sinks that return true from [[#isActive]], which then must
-   * implement it.
-   */
   override def create(materializer: ActorFlowMaterializerImpl, flowName: String): (Subscriber[In], Publisher[In]) = {
     val pub = new VirtualPublisher[In]
     val sub = new VirtualSubscriber[In](pub)
@@ -154,10 +150,6 @@ final class SubscriberSink[In](subscriber: Subscriber[In], val attributes: Opera
  */
 final class CancelSink(val attributes: OperationAttributes, shape: SinkShape[Any]) extends SinkModule[Any, Unit](shape) {
 
-  /**
-   * This method is only used for Sinks that return true from [[#isActive]], which then must
-   * implement it.
-   */
   override def create(materializer: ActorFlowMaterializerImpl, flowName: String): (Subscriber[Any], Unit) = {
     val subscriber = new Subscriber[Any] {
       override def onError(t: Throwable): Unit = ()
diff --git a/akka-stream/src/main/scala/akka/stream/impl/Sources.scala b/akka-stream/src/main/scala/akka/stream/impl/Sources.scala
index 440c8e6ec7..faf1583577 100644
--- a/akka-stream/src/main/scala/akka/stream/impl/Sources.scala
+++ b/akka-stream/src/main/scala/akka/stream/impl/Sources.scala
@@ -41,10 +41,6 @@ abstract class SourceModule[+Out, +Mat](val shape: SourceShape[Out]) extends Mod
  */
 final class SubscriberSource[Out](val attributes: OperationAttributes, shape: SourceShape[Out]) extends SourceModule[Out, Subscriber[Out]](shape) {
 
-  /**
-   * This method is only used for Sources that return true from [[#isActive]], which then must
-   * implement it.
-   */
   override def create(materializer: ActorFlowMaterializerImpl, flowName: String): (Publisher[Out], Subscriber[Out]) = {
     val processor = new Processor[Out, Out] {
       @volatile private var subscriber: Subscriber[_ >: Out] = null
diff --git a/akka-stream/src/main/scala/akka/stream/impl/StreamSubscriptionTimeout.scala b/akka-stream/src/main/scala/akka/stream/impl/StreamSubscriptionTimeout.scala
index de9a21a1cc..3662ceec4f 100644
--- a/akka-stream/src/main/scala/akka/stream/impl/StreamSubscriptionTimeout.scala
+++ b/akka-stream/src/main/scala/akka/stream/impl/StreamSubscriptionTimeout.scala
@@ -44,12 +44,13 @@ object StreamSubscriptionTimeoutSupport {
 }
 
 /**
+ * INTERNAL API
  * Provides support methods to create Publishers and Subscribers which time-out gracefully,
  * and are cancelled subscribing an `CancellingSubscriber` to the publisher, or by calling `onError` on the timed-out subscriber.
  *
  * See `akka.stream.materializer.subscription-timeout` for configuration options.
  */
-trait StreamSubscriptionTimeoutSupport {
+private[akka] trait StreamSubscriptionTimeoutSupport {
   this: Actor with ActorLogging ⇒
 
   import StreamSubscriptionTimeoutSupport._
@@ -107,4 +108,7 @@ trait StreamSubscriptionTimeoutSupport {
   protected def handleSubscriptionTimeout(target: Publisher[_], cause: Exception): Unit
 }
 
-class SubscriptionTimeoutException(msg: String) extends RuntimeException(msg)
+/**
+ * INTERNAL API
+ */
+private[akka] class SubscriptionTimeoutException(msg: String) extends RuntimeException(msg)
diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/FlexiMerge.scala b/akka-stream/src/main/scala/akka/stream/javadsl/FlexiMerge.scala
index 1ca7173ade..098884eecd 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/FlexiMerge.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/FlexiMerge.scala
@@ -67,10 +67,10 @@ object FlexiMerge {
    * Provides typesafe accessors to values from inputs supplied to [[ReadAll]].
    */
   final class ReadAllInputs(map: immutable.Map[InPort, Any]) extends ReadAllInputsBase {
-    /** Returns the value for the given [[InputPort]], or `null` if this input was cancelled. */
+    /** Returns the value for the given [[Inlet]], or `null` if this input was cancelled. */
     def get[T](input: Inlet[T]): T = getOrDefault(input, null)
 
-    /** Returns the value for the given [[InputPort]], or `defaultValue`. */
+    /** Returns the value for the given [[Inlet]], or `defaultValue`. */
     def getOrDefault[T, B >: T](input: Inlet[T], defaultValue: B): T = map.getOrElse(input, defaultValue).asInstanceOf[T]
   }
 
diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala b/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala
index db39842d22..ad6f2984f8 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/FlexiRoute.scala
@@ -54,9 +54,8 @@ object FlexiRoute {
    */
   trait RouteLogicContext[In] extends RouteLogicContextBase[In] {
     /**
-     * Emit one element downstream. It is only allowed to `emit` when
-     * [[#isDemandAvailable]] is `true` for the given `output`, otherwise
-     * `IllegalArgumentException` is thrown.
+     * Emit one element downstream. It is only allowed to `emit` at most one element to
+     * each output in response to `onInput`, `IllegalStateException` is thrown.
      */
     def emit[T](output: Outlet[T], elem: T): Unit
   }
diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala b/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala
index 722015daa6..e16cc3de90 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/Flow.scala
@@ -384,7 +384,7 @@ class Flow[-In, +Out, +Mat](delegate: scaladsl.Flow[In, Out, Mat]) extends Graph
  */
 trait RunnableFlow[+Mat] extends Graph[ClosedShape, Mat] {
   /**
-   * Run this flow and return the [[MaterializedMap]] containing the values for the [[KeyedMaterializable]] of the flow.
+   * Run this flow and return the materialized values of the flow.
    */
   def run(materializer: FlowMaterializer): Mat
   /**
diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/Graph.scala b/akka-stream/src/main/scala/akka/stream/javadsl/Graph.scala
index 63cd51d487..8c59b73d86 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/Graph.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/Graph.scala
@@ -273,9 +273,9 @@ object FlowGraph {
   val factory: GraphCreate = new GraphCreate {}
 
   /**
-   * Start building a [[FlowGraph]] or [[PartialFlowGraph]].
+   * Start building a [[FlowGraph]].
    *
-   * The [[FlowGraphBuilder]] is mutable and not thread-safe,
+   * The [[Builder]] is mutable and not thread-safe,
    * thus you should construct your Graph and then share the constructed immutable [[FlowGraph]].
    */
   def builder(): Builder = new Builder()(new scaladsl.FlowGraph.Builder)
diff --git a/akka-stream/src/main/scala/akka/stream/javadsl/StreamTcp.scala b/akka-stream/src/main/scala/akka/stream/javadsl/StreamTcp.scala
index df718d0c94..d5f9f89541 100644
--- a/akka-stream/src/main/scala/akka/stream/javadsl/StreamTcp.scala
+++ b/akka-stream/src/main/scala/akka/stream/javadsl/StreamTcp.scala
@@ -26,14 +26,13 @@ object StreamTcp extends ExtensionId[StreamTcp] with ExtensionIdProvider {
    */
   class ServerBinding private[akka] (delegate: scaladsl.StreamTcp.ServerBinding) {
     /**
-     * The local address of the endpoint bound by the materialization of the `connections` [[Source]]
-     * whose [[MaterializedMap]] is passed as parameter.
+     * The local address of the endpoint bound by the materialization of the `connections` [[Source]].
      */
     def localAddress: InetSocketAddress = delegate.localAddress
 
     /**
      * Asynchronously triggers the unbinding of the port that was bound by the materialization of the `connections`
-     * [[Source]] whose [[MaterializedMap]] is passed as parameter.
+     * [[Source]].
      *
      * The produced [[scala.concurrent.Future]] is fulfilled when the unbinding has been completed.
      */
@@ -56,7 +55,7 @@ object StreamTcp extends ExtensionId[StreamTcp] with ExtensionIdProvider {
 
     /**
      * Handles the connection using the given flow, which is materialized exactly once and the respective
-     * [[MaterializedMap]] returned.
+     * materialized value is returned.
      *
      * Convenience shortcut for: `flow.join(handler).run()`.
      */
@@ -80,8 +79,7 @@ object StreamTcp extends ExtensionId[StreamTcp] with ExtensionIdProvider {
     def remoteAddress: InetSocketAddress = delegate.remoteAddress
 
     /**
-     * The local address of the endpoint bound by the materialization of the connection materialization
-     * whose [[MaterializedMap]] is passed as parameter.
+     * The local address of the endpoint bound by the materialization of the connection materialization.
      */
     def localAddress: InetSocketAddress = delegate.localAddress
   }
diff --git a/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala b/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala
index 7b5d1147e2..8e6d297ab7 100644
--- a/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala
+++ b/akka-stream/src/main/scala/akka/stream/scaladsl/Flow.scala
@@ -129,8 +129,8 @@ final class Flow[-In, +Out, +Mat](private[stream] override val module: Module)
 
   /**
    * Connect the `Source` to this `Flow` and then connect it to the `Sink` and run it. The returned tuple contains
-   * the materialized values of the `Source` and `Sink`, e.g. the `Subscriber` of a [[SubscriberSource]] and
-   * and `Publisher` of a [[PublisherSink]].
+   * the materialized values of the `Source` and `Sink`, e.g. the `Subscriber` of a of a [[Source#subscriber]] and
+   * and `Publisher` of a [[Sink#publisher]].
    */
   def runWith[Mat1, Mat2](source: Source[In, Mat1], sink: Sink[Out, Mat2])(implicit materializer: FlowMaterializer): (Mat1, Mat2) = {
     source.via(this).toMat(sink)(Keep.both).run()
diff --git a/akka-stream/src/main/scala/akka/stream/scaladsl/ImplicitFlowMaterializer.scala b/akka-stream/src/main/scala/akka/stream/scaladsl/ImplicitFlowMaterializer.scala
index 95d0113fd8..05ce63fa60 100644
--- a/akka-stream/src/main/scala/akka/stream/scaladsl/ImplicitFlowMaterializer.scala
+++ b/akka-stream/src/main/scala/akka/stream/scaladsl/ImplicitFlowMaterializer.scala
@@ -12,13 +12,13 @@ import akka.stream.ActorFlowMaterializer
  * [[akka.stream.FlowMaterializer]] in scope.
  *
  * Subclass may override [[#flowMaterializerSettings]] to define custom
- * [[akka.stream.FlowMaterializerSettings]] for the `FlowMaterializer`.
+ * [[akka.stream.ActorFlowMaterializerSettings]] for the `FlowMaterializer`.
  */
 trait ImplicitFlowMaterializer { this: Actor ⇒
 
   /**
    * Subclass may override this to define custom
-   * [[akka.stream.FlowMaterializerSettings]] for the `FlowMaterializer`.
+   * [[akka.stream.ActorFlowMaterializerSettings]] for the `FlowMaterializer`.
    */
   def flowMaterializerSettings: ActorFlowMaterializerSettings = ActorFlowMaterializerSettings(context.system)
 
diff --git a/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala b/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala
index 8b24909a11..2f78c9bb4e 100644
--- a/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala
+++ b/akka-stream/src/main/scala/akka/stream/scaladsl/Sink.scala
@@ -26,7 +26,7 @@ final class Sink[-In, +Mat](private[stream] override val module: Module)
 
   /**
    * Connect this `Sink` to a `Source` and run it. The returned value is the materialized value
-   * of the `Source`, e.g. the `Subscriber` of a [[SubscriberSource]].
+   * of the `Source`, e.g. the `Subscriber` of a [[Source#subscriber]].
    */
   def runWith[Mat2](source: Source[In, Mat2])(implicit materializer: FlowMaterializer): Mat2 =
     source.to(this).run()
diff --git a/akka-stream/src/main/scala/akka/stream/stage/Stage.scala b/akka-stream/src/main/scala/akka/stream/stage/Stage.scala
index bd21d903b2..bfc80dfe83 100644
--- a/akka-stream/src/main/scala/akka/stream/stage/Stage.scala
+++ b/akka-stream/src/main/scala/akka/stream/stage/Stage.scala
@@ -174,7 +174,7 @@ abstract class PushStage[In, Out] extends PushPullStage[In, Out] {
  * (resulting in two signals).
  *
  * However, DetachedStages have the ability to call [[akka.stream.stage.DetachedContext#hold]] as a response to
- * [[#onPush]] and [[akka.stream.stage.DetachedContext##onPull]] which temporarily takes the signal off and
+ * [[#onPush]] and [[#onPull]] which temporarily takes the signal off and
  * stops execution, at the same time putting the stage in an [[akka.stream.stage.DetachedContext#isHolding]] state.
  * If the stage is in a holding state it contains one absorbed signal, therefore in this state the only possible
  * command to call is [[akka.stream.stage.DetachedContext#pushAndPull]] which results in two events making the