Add mentions to akka.stream.impl.package and fix some typos. (Fixes #23073) (#23075)

akka-stream/src/main/scala/akka/stream/impl/TraversalBuilder.scala

@@ -33,7 +33,7 @@ import scala.collection.immutable.Map.Map1
  * The Traversal is designed to be position independent so that multiple traversals can be composed relatively
  * simply. This particular feature also avoids issues with multiply imported modules where the identity must
  * be encoded somehow. The two imports don't need any special treatment as they are at different positions in
- * the traversal. See [[MaterializeAtomic]] for more details.
+ * the traversal. See [[MaterializeAtomic]] and comments in akka.stream.impl.package for more details.
  */
 @InternalApi private[akka] sealed trait Traversal {
 
@@ -345,7 +345,7 @@ import scala.collection.immutable.Map.Map1
  *
  * The resulting Traversal can be accessed via the `traversal` method once the graph is completed (all ports are
  * wired). The Traversal may be accessed earlier, depending on the type of the builder and certain conditions.
- * See [[CompositeTraversalBuilder]] and [[LinearTraversalBuilder]].
+ * See [[CompositeTraversalBuilder]] and [[LinearTraversalBuilder]], also comments in akka.stream.impl.package for more details.
  */
 @DoNotInherit private[akka] sealed trait TraversalBuilder {
 
@@ -397,7 +397,7 @@ import scala.collection.immutable.Map.Map1
   def isUnwired(out: OutPort): Boolean
 
   /**
-   * Returns whether the given output port has been wired in the graph or not.
+   * Returns whether the given input port has been wired in the graph or not.
    */
   def isUnwired(in: InPort): Boolean
 
@@ -448,6 +448,7 @@ import scala.collection.immutable.Map.Map1
  * INTERNAL API
  *
  * Returned by [[CompositeTraversalBuilder]] once all output ports of a subgraph has been wired.
+ * See comments in akka.stream.impl.package for more details.
  */
 @InternalApi private[akka] final case class CompletedTraversalBuilder(
   traversalSoFar: Traversal,
@@ -512,6 +513,7 @@ import scala.collection.immutable.Map.Map1
  *
  * Represents a builder that contains a single atomic module. Its primary purpose is to track and build the
  * outToSlot array which will be then embedded in a [[MaterializeAtomic]] Traversal step.
+ * See comments in akka.stream.impl.package for more details.
  */
 @InternalApi private[akka] final case class AtomicTraversalBuilder(
   module:      AtomicModule[Shape, Any],
@@ -677,6 +679,7 @@ import scala.collection.immutable.Map.Map1
  * [[CompositeTraversalBuilder]] are embedded. These are not guaranteed to have their unwired input/output ports
  * in a fixed location, therefore the last step of the Traversal might need to be changed in those cases from the
  * -1 relative offset to something else (see rewireLastOutTo).
+ * See comments in akka.stream.impl.package for more details.
  */
 @InternalApi private[akka] final case class LinearTraversalBuilder(
   inPort:               OptionVal[InPort],
@@ -833,7 +836,7 @@ import scala.collection.immutable.Map.Map1
           throw new IllegalArgumentException("Appended linear module must have an unwired input port because there is a dangling output.")
 
         /*
-         * To understand how append work, first the general structure of the LinearTraversalBuilder must be
+         * To understand how append works, first the general structure of the LinearTraversalBuilder must be
          * understood. The most general structure of LinearTraversalBuilder looks like this (in Flow DSL order):
          *
          *   traversalSoFar ~ pendingBuilder ~ beforeBuilder
@@ -916,7 +919,7 @@ import scala.collection.immutable.Map.Map1
              * This is the case where our last module is a composite, and since it does not have its output port
              * wired yet, the traversal is split into the parts, traversalSoFar, pendingBuilder and beforeBuilder.
              *
-             * Since will wire now the output port, we can assemble everything together:
+             * Since we will wire now the output port, we can assemble everything together:
              */
             val out = outPort.get
             /*
@@ -1071,6 +1074,7 @@ import scala.collection.immutable.Map.Map1
  * reason why this is needed is because the builder is referenced at various places, while it needs to be mutated.
  * In an immutable data structure this is best done with an indirection, i.e. places refer to this immutable key and
  * look up the current state in an extra Map.
+ * See comments in akka.stream.impl.package for more details.
  */
 @InternalApi private[akka] final class BuilderKey extends TraversalBuildStep {
   override def toString = s"K:$hashCode"
@@ -1092,6 +1096,7 @@ import scala.collection.immutable.Map.Map1
  * in a non-deterministic order (depending on wiring order) would mess up all relative addressing. This is the
  * primary technical reason why a reverseTraversal list is maintained and the Traversal can only be completed once
  * all output ports have been wired.
+ * See comments in akka.stream.impl.package for more details.
  *
  * @param reverseBuildSteps Keeps track of traversal steps that needs to be concatenated. This is basically
  *                         a "queue" of BuilderKeys that point to builders of submodules/subgraphs. Since it is

akka-stream/src/main/scala/akka/stream/impl/package.scala

@@ -186,7 +186,7 @@ package akka.stream
  *
  *  The simpler case is the [[akka.stream.impl.LinearTraversalBuilder]]. This builder only allows building linear
  *  chains of stages, hence, it can only have at most one [[OutPort]] and [[InPort]] unwired. Since there is no
- *  possible disambiguity between these two port types, there is no need for port mapping for these. Conversely,
+ *  possible ambiguity between these two port types, there is no need for port mapping for these. Conversely,
  *  for those internal ports that are already wired, there is no need for port mapping as their relative wiring
  *  is not ambiguous (see previous section). As a result, the [[akka.stream.impl.LinearTraversalBuilder]] does not
  *  use any port mapping.
@@ -306,7 +306,7 @@ package akka.stream
  *  this composite and delay construction of its part of the traversal. For details see [[akka.stream.impl.LinearTraversalBuilder]]
  *  as these cases are heavily commented and explained in the code.
  *
- *  There is another pecularity of the linear builder we need to explain. Namely, it builds the traversal in reverse
+ *  There is another peculiarity of the linear builder we need to explain. Namely, it builds the traversal in reverse
  *  order, i.e. from Sinks towards Sources. THIS CAN BE SUPER CONFUSING AT TIMES SO PAY ATTENTION! There are two
  *  important reasons why this is needed:
  *