Documentation fixes (#30740)

akka-docs/src/main/paradox/general/supervision.md

@@ -33,7 +33,7 @@ provides the following three strategies:
 Since actors are part of a hierarchy it can often make sense to propagate
 the permanent failures upwards, if all children of an actor has stopped
 unexpectedly it may make sense for the actor itself to restart or stop to
-get back to a functional state. This can achieved through a combination of
+get back to a functional state. This can be achieved through a combination of
 supervision and watching the children to get notified when they terminate.
 An example of this can be found in @ref:[Bubble failures up through the hierarchy](../typed/fault-tolerance.md#bubble).
 

akka-docs/src/main/paradox/general/terminology.md

@@ -61,7 +61,7 @@ the two resources, never acquiring it, but always yielding to the other.
 We call it a *Race condition* when an assumption about the ordering of a set of events might be violated by external
 non-deterministic effects. Race conditions often arise when multiple threads have a shared mutable state, and the
 operations of thread on the state might be interleaved causing unexpected behavior. While this is a common case, shared
-state is not necessary to have race conditions. One example could be a client sending unordered packets (e.g UDP
+state is not necessary to have race conditions. One example could be a client sending unordered packets (e.g. UDP
 datagrams) `P1`, `P2` to a server. As the packets might potentially travel via different network routes, it is possible that
 the server receives `P2` first and `P1` afterwards. If the messages contain no information about their sending order it is
 impossible to determine by the server that they were sent in a different order. Depending on the meaning of the packets

akka-docs/src/main/paradox/logging.md

@@ -162,7 +162,7 @@ akka {
 }
 ```
 
-If you want very detailed logging of all lifecycle changes of Actors (restarts, deaths etc):
+If you want very detailed logging of all lifecycle changes of Actors (restarts, deaths etc.):
 
 ```ruby
 akka {

akka-docs/src/main/paradox/stream/actor-interop.md

@@ -54,7 +54,7 @@ is already a message in the mailbox when the actor has completed previous
 message.
 
 The actor must reply to the @scala[`sender()`]@java[`getSender()`] for each message from the stream. That
-reply will complete the  @scala[`Future`]@java[`CompletionStage`] of the `ask` and it will be the element that is emitted downstreams.
+reply will complete the  @scala[`Future`]@java[`CompletionStage`] of the `ask` and it will be the element that is emitted downstream.
 
 In case the target actor is stopped, the operator will fail with an `AskStageTargetActorTerminatedException`
 
@@ -111,7 +111,7 @@ Java
 
 Note that replying to the sender of the elements (the "stream") is required as lack of those ack signals would be interpreted
 as back-pressure (as intended), and no new elements will be sent into the actor until it acknowledges some elements.
-Handling the other signals while is not required, however is a good practice, to see the state of the streams lifecycle
+Handling the other signals while is not required, however is a good practice, to see the state of the stream's lifecycle
 in the connected actor as well. Technically it is also possible to use multiple sinks targeting the same actor,
 however it is not common practice to do so, and one should rather investigate using a `Merge` operator for this purpose.
 

akka-docs/src/main/paradox/stream/futures-interop.md

@@ -35,7 +35,7 @@ Scala
 Java
 :   @@snip [IntegrationDocTest.java](/akka-docs/src/test/java/jdocs/stream/IntegrationDocTest.java) { #tweet-authors }
 
-Assume that we can lookup their email address using:
+Assume that we can look up their email address using:
 
 Scala
 :   @@snip [IntegrationDocSpec.scala](/akka-docs/src/test/scala/docs/stream/IntegrationDocSpec.scala) { #email-address-lookup }
@@ -62,7 +62,7 @@ Java
 
 `mapAsync` is applying the given function that is calling out to the external service to
 each of the elements as they pass through this processing step. The function returns a @scala[`Future`]@java[`CompletionStage`]
-and the value of that future will be emitted downstreams. The number of Futures
+and the value of that future will be emitted downstream. The number of Futures
 that shall run in parallel is given as the first argument to `mapAsync`.
 These Futures may complete in any order, but the elements that are emitted
 downstream are in the same order as received from upstream.
@@ -214,7 +214,7 @@ Note that `after` lines are in the same order as the `before` lines even
 though elements are `completed` in a different order. For example `H`
 is `completed` before `g`, but still emitted afterwards.
 
-The numbers in parenthesis illustrates how many calls that are in progress at
+The numbers in parentheses illustrate how many calls that are in progress at
 the same time. Here the downstream demand and thereby the number of concurrent
 calls are limited by the buffer size (4) set with an attribute.
 
@@ -274,6 +274,6 @@ after: I
 Note that `after` lines are not in the same order as the `before` lines. For example
 `H` overtakes the slow `G`.
 
-The numbers in parenthesis illustrates how many calls that are in progress at
+The numbers in parentheses illustrate how many calls that are in progress at
 the same time. Here the downstream demand and thereby the number of concurrent
 calls are limited by the buffer size (4) set with an attribute.

akka-docs/src/main/paradox/stream/operators/Source-or-Flow/throttle.md

@@ -45,7 +45,7 @@ The extra argument to set the `ThrottleMode` to `shapping` tells `throttle` to m
 the maximum rate. Alternatively we could set the throttling mode to cause a stream failure when upstream is faster
 than the throttle rate.   
 
-The examples above don't cover all the parameters supported by `throttle` (e.g `cost`-based throttling). See the 
+The examples above don't cover all the parameters supported by `throttle` (e.g. `cost`-based throttling). See the 
 @apidoc[api documentation](Flow) { scala="#throttle(cost:Int,per:scala.concurrent.duration.FiniteDuration,maximumBurst:Int,costCalculation:Out=>Int,mode:akka.stream.ThrottleMode):FlowOps.this.Repr[Out]" java="#throttle(int,java.time.Duration,int,akka.japi.function.Function,akka.stream.ThrottleMode)" }
 for all the details.
 

akka-docs/src/main/paradox/stream/operators/Source/unfold.md

@@ -32,7 +32,7 @@ Java
  :   @@snip [Unfold.java](/akka-docs/src/test/java/jdocs/stream/operators/source/Unfold.java) { #countdown }
 
 
-It is also possible to express unfolds that don't have an end, which will never return @scala[`None`] @java[`Optional.empty`] and must be combined with for example `.take(n)` to not produce infinite streams. Here we have implemented the Fibonacci numbers (0, 1, 1, 2, 3, 5, 8, 13, etc) with `unfold`:
+It is also possible to express unfolds that don't have an end, which will never return @scala[`None`] @java[`Optional.empty`] and must be combined with for example `.take(n)` to not produce infinite streams. Here we have implemented the Fibonacci numbers (0, 1, 1, 2, 3, 5, 8, 13, etc.) with `unfold`:
 
 Scala
  :   @@snip [Unfold.scala](/akka-docs/src/test/scala/docs/stream/operators/source/Unfold.scala) { #fibonacci }

akka-docs/src/main/paradox/stream/reactive-streams-interop.md

@@ -66,7 +66,7 @@ Java
 The `Publisher` is used as an input `Source` to the flow and the
 `Subscriber` is used as an output `Sink`.
 
-A `Flow` can also be also converted to a `RunnableGraph[Processor[In, Out]]` which
+A `Flow` can also be converted to a `RunnableGraph[Processor[In, Out]]` which
 materializes to a `Processor` when `run()` is called. `run()` itself can be called multiple
 times, resulting in a new `Processor` instance each time.
 

akka-docs/src/main/paradox/stream/stream-composition.md

@@ -166,7 +166,7 @@ Java
 :   @@snip [CompositionDocTest.java](/akka-docs/src/test/java/jdocs/stream/CompositionDocTest.java) { #partial-graph }
 
 The only new addition is the return value of the builder block, which is a `Shape`. All operators (including
-`Source`, `BidiFlow`, etc) have a shape, which encodes the *typed* ports of the module. In our example
+`Source`, `BidiFlow`, etc.) have a shape, which encodes the *typed* ports of the module. In our example
 there is exactly one input and output port left, so we can declare it to have a `FlowShape` by returning an
 instance of it. While it is possible to create new `Shape` types, it is usually recommended to use one of the
 matching built-in ones.

akka-docs/src/main/paradox/stream/stream-context.md

@@ -27,8 +27,8 @@ would have no way to determine whether an element was skipped
 or merely reordered and still in flight.
 
 For this reason, @apidoc[FlowWithContext] allows filtering operations
-(such as `filter`, `filterNot`, `collect`, etc) and grouping operations
-(such as `grouped`, `sliding`, etc) but not reordering operations
+(such as `filter`, `filterNot`, `collect`, etc.) and grouping operations
+(such as `grouped`, `sliding`, etc.) but not reordering operations
 (such as `mapAsyncUnordered` and `statefulMapConcat`). Finally,
 also 'one-to-n' operations such as `mapConcat` are allowed.
 

akka-docs/src/main/paradox/stream/stream-dynamic.md

@@ -228,7 +228,7 @@ Scala
 Java
 :   @@snip [HubDocTest.java](/akka-docs/src/test/java/jdocs/stream/HubDocTest.java) { #partition-hub-stateful }
 
-Note that it is a factory of a function to to be able to hold stateful variables that are 
+Note that it is a factory of a function to be able to hold stateful variables that are 
 unique for each materialization. @java[In this example the `partitioner` function is implemented as a class to
 be able to hold the mutable variable. A new instance of `RoundRobin` is created for each materialization of the hub.]
 

akka-docs/src/main/paradox/typed/durable-state/persistence.md

@@ -108,7 +108,7 @@ More effects are explained in @ref:[Effects and Side Effects](#effects-and-side-
 
 In addition to returning the primary `Effect` for the command, `DurableStateBehavior`s can also 
 chain side effects that are to be performed after successful persist which is achieved with the `thenRun`
-function e.g @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`].
+function e.g. @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`].
 
 ### Completing the example
 
@@ -171,7 +171,7 @@ Note that only one of those can be chosen per incoming command. It is not possib
 
 In addition to returning the primary `Effect` for the command `DurableStateBehavior`s can also 
 chain side effects that are to be performed after successful persist which is achieved with the `thenRun`
-function that runs the callback passed to it e.g @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`]. 
+function that runs the callback passed to it e.g. @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`]. 
 
 All `thenRun` registered callbacks are executed sequentially after successful execution of the persist statement
 (or immediately, in case of `none` and `unhandled`).

akka-docs/src/main/paradox/typed/persistence.md

@@ -152,7 +152,7 @@ More effects are explained in @ref:[Effects and Side Effects](#effects-and-side-
 
 In addition to returning the primary `Effect` for the command `EventSourcedBehavior`s can also 
 chain side effects that are to be performed after successful persist which is achieved with the `thenRun`
-function e.g @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`].
+function e.g. @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`].
 
 ### Event handler
 
@@ -235,7 +235,7 @@ Note that only one of those can be chosen per incoming command. It is not possib
 
 In addition to returning the primary `Effect` for the command `EventSourcedBehavior`s can also 
 chain side effects that are to be performed after successful persist which is achieved with the `thenRun`
-function e.g @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`].
+function e.g. @scala[`Effect.persist(..).thenRun`]@java[`Effect().persist(..).thenRun`].
 
 In the example below the state is sent to the `subscriber` ActorRef. Note that the new state after applying 
 the event is passed as parameter of the `thenRun` function. In the case where multiple events have been persisted,