Incorporate some classic actor docs in Actors Typed where applicable (#27866)

* Incorporate some classic actor docs in Actors Typed where applicable #24717

* Moved classic actor exception and message handling in failure section to general supervision, and other suggestions.

* Relocated the actors and exceptions supervision link to a better spot.

* Updated the typed supervision entry in fault tolerance.

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

@@ -6,7 +6,7 @@
 
 ## Dependency
 
-To use Classic Actors, you must add the following dependency in your project:
+To use Classic Actors, add the following dependency in your project:
 
 @@dependency[sbt,Maven,Gradle] {
   group="com.typesafe.akka"
@@ -32,9 +32,10 @@ its syntax from Erlang.
 @@@ note
 
 Since Akka enforces parental supervision every actor is supervised and
-(potentially) the supervisor of its children, it is advisable that you
-familiarize yourself with @ref:[Actor Systems](general/actor-systems.md) and @ref:[supervision](general/supervision.md)
-and it may also help to read @ref:[Actor References, Paths and Addresses](general/addressing.md).
+(potentially) the supervisor of its children, it is advisable to
+familiarize yourself with @ref:[Actor Systems](general/actor-systems.md), @ref:[supervision](general/supervision.md)
+and @ref:[handling exceptions](general/supervision.md#actors-and-exceptions)
+as well as @ref:[Actor References, Paths and Addresses](general/addressing.md).
 
 @@@
 
@@ -776,7 +777,6 @@ Java
 
 ## Receive messages
 
-
 An Actor has to
 @scala[implement the `receive` method to receive messages:]
 @java[define its initial receive behavior by implementing the `createReceive` method in the `AbstractActor`:]
@@ -1273,35 +1273,6 @@ then you should use the @scala[`UnboundedStash` trait] @java[`AbstractActorWithU
 
 @@@
 
-
-## Actors and exceptions
-
-It can happen that while a message is being processed by an actor, that some
-kind of exception is thrown, e.g. a database exception.
-
-### What happens to the Message
-
-If an exception is thrown while a message is being processed (i.e. taken out of
-its mailbox and handed over to the current behavior), then this message will be
-lost. It is important to understand that it is not put back on the mailbox. So
-if you want to retry processing of a message, you need to deal with it yourself
-by catching the exception and retry your flow. Make sure that you put a bound
-on the number of retries since you don't want a system to livelock (so
-consuming a lot of cpu cycles without making progress).
-
-### What happens to the mailbox
-
-If an exception is thrown while a message is being processed, nothing happens to
-the mailbox. If the actor is restarted, the same mailbox will be there. So all
-messages on that mailbox will be there as well.
-
-### What happens to the actor
-
-If code within an actor throws an exception, that actor is suspended and the
-supervision process is started (see @ref:[supervision](general/supervision.md)). Depending on the
-supervisor’s decision the actor is resumed (as if nothing happened), restarted
-(wiping out its internal state and starting from scratch) or terminated.
-
 @@@ div { .group-scala }
 
 ## Extending Actors using PartialFunction chaining

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

@@ -104,6 +104,32 @@ message will be delivered irrespective of the order in which the monitoring
 request and target’s termination occur, i.e. you still get the message even if
 at the time of registration the target is already dead.
 
-
+## Actors and exceptions
+
+It can happen that while a message is being processed by an actor, that some
+kind of exception is thrown, e.g. a database exception.
+
+### What happens to the Message
+
+If an exception is thrown while a message is being processed (i.e. taken out of
+its mailbox and handed over to the current behavior), then this message will be
+lost. It is important to understand that it is not put back on the mailbox. So
+if you want to retry processing of a message, you need to deal with it yourself
+by catching the exception and retry your flow. Make sure that you put a bound
+on the number of retries since you don't want a system to livelock (so
+consuming a lot of cpu cycles without making progress).
+
+### What happens to the mailbox
+
+If an exception is thrown while a message is being processed, nothing happens to
+the mailbox. If the actor is restarted, the same mailbox will be there. So all
+messages on that mailbox will be there as well.
+
+### What happens to the actor
+
+If code within an actor throws an exception, that actor is suspended and the
+supervision process is started. Depending on the
+supervisor’s decision the actor is resumed (as if nothing happened), restarted
+(wiping out its internal state and starting from scratch) or terminated.
 
 

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

@@ -11,7 +11,7 @@ For the Akka Classic documentation of this feature see @ref:[Classic Actors](../
 
 ## Dependency
 
-To use Akka Actor Typed, you must add the following dependency in your project:
+To use Akka Actors, add the following dependency in your project:
 
 @@dependency[sbt,Maven,Gradle] {
   group=com.typesafe.akka
@@ -19,13 +19,27 @@ To use Akka Actor Typed, you must add the following dependency in your project:
   version=$akka.version$
 }
 
+## Akka Actors
+
+The [Actor Model](http://en.wikipedia.org/wiki/Actor_model) provides a higher level of abstraction for writing concurrent
+and distributed systems. It alleviates the developer from having to deal with
+explicit locking and thread management, making it easier to write correct
+concurrent and parallel systems. Actors were defined in the 1973 paper by Carl
+Hewitt but have been popularized by the Erlang language, and used for example at
+Ericsson with great success to build highly concurrent and reliable telecom
+systems. The API of Akka’s Actors has borrowed some of its syntax from Erlang.
+ 
 ## First example
 
 If you are new to Akka you might want to start with reading the @ref:[Getting Started Guide](guide/introduction.md)
-and then come back here to learn more.
+and then come back here to learn more. 
+
+It is helpful to become familiar with the foundational, external and internal
+ecosystem of your Actors, to see what you can leverage and customize as needed, see
+@ref:[Actor Systems](../general/actor-systems.md) and @ref:[Actor References, Paths and Addresses](../general/addressing.md).
 
 As discussed in @ref:[Actor Systems](../general/actor-systems.md) Actors are about
-sending messages between independent units of computation, but how does that
+sending messages between independent units of computation, but what does that
 look like?
 
 In all of the following these imports are assumed:
@@ -80,7 +94,7 @@ protocol but Actors can model arbitrarily complex protocols when needed. The
 protocol is bundled together with the behavior that implements it in a nicely
 wrapped scope—the `HelloWorld` @scala[object]@java[class].
 
-As Carl Hewitt said, one Actor is no Actor—it would be quite lonely with
+As Carl Hewitt said, one Actor is no Actor — it would be quite lonely with
 nobody to talk to. We need another Actor that interacts with the `Greeter`.
 Let's make a `HelloWorldBot` that receives the reply from the `Greeter` and sends a number
 of additional greeting messages and collect the replies until a given max number

akka-docs/src/main/paradox/typed/fault-tolerance.md

@@ -9,17 +9,17 @@ will by default be stopped.
 
 @@@ note
 
-An important difference between Typed and Classic actors is that Typed actors are by default stopped if
-an exception is thrown and no supervision strategy is defined while in Classic they are restarted.
+An important difference between @ref:[Typed actors](actors.md) and @ref:[Classic actors](../actors.md) is that 
+by default: the former are stopped if an exception is thrown and no supervision strategy is defined while in Classic they are restarted.
 
 @@@
 
 Note that there is an important distinction between failures and validation errors:
 
-A validation error means that the data of a command sent to an actor is not valid, this should rather be modelled as a
+A **validation error** means that the data of a command sent to an actor is not valid, this should rather be modelled as a
 part of the actor protocol than make the actor throw exceptions.
 
-A failure is instead something unexpected or outside the control of the actor itself, for example a database connection
+A **failure** is instead something unexpected or outside the control of the actor itself, for example a database connection
 that broke. Opposite to validation errors, it is seldom useful to model such as parts of the protocol as a sending actor
 very seldom can do anything useful about it.
 
@@ -30,10 +30,11 @@ with a fresh state that we know is valid.
 
 ## Supervision
 
-In Akka this "somewhere else" is called supervision. Supervision allows you to declaratively describe what should happen when a certain type of exceptions are thrown inside an actor. 
+In Akka this "somewhere else" is called supervision. Supervision allows you to declaratively describe what should happen when certain types of exceptions are thrown inside an actor. 
 
-To use supervision the actual Actor behavior is wrapped using `Behaviors.supervise`. Typically you would wrap the actor
- with supervision in the parent when spawning it as a child.
+The default @ref:[supervision](../general/supervision.md) strategy is to stop the actor if an exception is thrown. 
+In many cases you will want to further customize this behavior. To use supervision the actual Actor behavior is wrapped using `Behaviors.supervise`. 
+Typically you would wrap the actor with supervision in the parent when spawning it as a child.
  
 This example restarts the actor when it fails with an `IllegalStateException`: