Correct serializer loading and supervision documentation

docs/articles/actors/routers.md

@@ -96,7 +96,7 @@ Routers are implemented as actors, so a router is supervised by its parent, and
 
 *Pool routers* on the other hand create their own children. The router is therefore also the routee's supervisor.
 
-By default, pool routers use a custom strategy that only returns `Escalate` for all exceptions, the router supervising the failing worker will then escalate to its own parent, if the parent of the router decides to restart the router, all the pool workers will also be recreated as a result of this.
+By default, pool routers use `Pool.DefaultSupervisorStrategy`, which is `SupervisorStrategy.DefaultStrategy`. This strategy restarts a routee for ordinary exceptions and stops it for `ActorInitializationException`, `ActorKilledException`, and `DeathPactException`.
 
 ## Routing Strategies
 

docs/articles/serialization/serialization.md

@@ -194,6 +194,8 @@ The only thing left to do for this class would be to fill in the serialization l
 Afterwards the configuration would need to be updated to reflect which name to bind to and the classes that use this
 serializer.
 
+When dynamic type loading is enabled and a custom serializer is configured by type name under `akka.actor.serializers`, Akka.NET uses the constructor taking `(ExtendedActorSystem, Config)` when `akka.actor.serialization-settings.<alias>` is non-empty, and the constructor taking only `ExtendedActorSystem` otherwise. It does not fall back to a parameterless constructor. With `SerializationSetup`, the setup factory supplies the serializer instances in `SerializerDetails` instead.
+
 ### Serializer Ids
 
 Serializer ids are part of the wire format: two nodes that disagree about an id cannot read each other's messages. Ids from 0 to 40 are reserved for Akka.NET.

src/core/Akka/Pattern/BackoffSupervisor.cs

@@ -180,13 +180,16 @@ private bool OnTerminated(object message)
         }
 
         /// <summary>
-        /// Props for creating a <see cref="BackoffSupervisor"/> actor.
+        /// Creates Props for a <see cref="BackoffSupervisor"/> using <see cref="SupervisorStrategy.DefaultStrategy"/>.
+        /// With this legacy overload, a <see cref="Directive.Restart"/> restarts the child immediately;
+        /// backoff is applied after the child terminates.
         /// </summary>
         /// <param name="childProps">The <see cref="Akka.Actor.Props"/> of the child actor that will be started and supervised</param>
         /// <param name="childName">Name of the child actor</param>
         /// <param name="minBackoff">Minimum (initial) duration until the child actor will started again, if it is terminated</param>
         /// <param name="maxBackoff">The exponential back-off is capped to this duration</param>
         /// <param name="randomFactor">After calculation of the exponential back-off an additional random delay based on this factor is added, e.g. `0.2` adds up to `20%` delay. In order to skip this additional delay pass in `0`.</param>
+        /// <returns>Props configured to create a <see cref="BackoffSupervisor"/>.</returns>
         public static Props Props(
             Props childProps,
             string childName,
@@ -198,18 +201,16 @@ public static Props Props(
         }
 
         /// <summary>
-        /// Props for creating a <see cref="BackoffSupervisor"/> actor.
-        /// 
-        /// Exceptions in the child are handled with the default supervision strategy, i.e.
-        /// most exceptions will immediately restart the child. You can define another
-        /// supervision strategy by using [[#propsWithSupervisorStrategy]].
+        /// Creates Props for a <see cref="BackoffSupervisor"/> using the default supervision strategy
+        /// with the specified retry limit. The strategy handles child failures; backoff is applied
+        /// when the child terminates.
         /// </summary>
         /// <param name="childProps">The <see cref="Akka.Actor.Props"/> of the child actor that will be started and supervised</param>
         /// <param name="childName">Name of the child actor</param>
         /// <param name="minBackoff">Minimum (initial) duration until the child actor will started again, if it is terminated</param>
         /// <param name="maxBackoff">The exponential back-off is capped to this duration</param>
         /// <param name="randomFactor">After calculation of the exponential back-off an additional random delay based on this factor is added, e.g. `0.2` adds up to `20%` delay. In order to skip this additional delay pass in `0`.</param>
-        /// <param name="maxNrOfRetries">Maximum number of attempts to restart the child actor. The supervisor will terminate itself after the maxNoOfRetries is reached. In order to restart infinitely pass in `-1`.</param>
+        /// <param name="maxNrOfRetries">Maximum backoff restarts between automatic resets. Up to this many restarts are allowed; a child termination that would exceed this backoff restart limit stops the supervisor. The counter resets after a replacement has run for <paramref name="minBackoff"/>. This value also sets the separate default <see cref="OneForOneStrategy"/> limit for immediate child-failure restarts. Pass <c>-1</c> for no retry limit.</param>
         /// <returns>A <see cref="Akka.Actor.Props"/> instance configured to create a <see cref="BackoffSupervisor"/>.</returns>
         public static Props Props(
             Props childProps,
@@ -237,14 +238,19 @@ public static Props Props(BackoffOptions options)
         }
 
         /// <summary>
-        /// Props for creating a <see cref="BackoffSupervisor"/> actor with a custom supervision strategy.
+        /// Creates Props for a <see cref="BackoffSupervisor"/> using the supplied child supervision strategy.
+        /// With this legacy overload, a <see cref="Directive.Restart"/> is handled immediately by the
+        /// supplied strategy; backoff is applied after the child terminates. To delay restart directives, use
+        /// <see cref="Props(BackoffOptions)"/> with <see cref="Backoff.OnFailure(Props, string, TimeSpan, TimeSpan, double, int)"/>;
+        /// that path stops the child and schedules its replacement after the backoff delay.
         /// </summary>
         /// <param name="childProps">The <see cref="Akka.Actor.Props"/> of the child actor that will be started and supervised</param>
         /// <param name="childName">Name of the child actor</param>
         /// <param name="minBackoff">Minimum (initial) duration until the child actor will started again, if it is terminated</param>
         /// <param name="maxBackoff">The exponential back-off is capped to this duration</param>
         /// <param name="randomFactor">After calculation of the exponential back-off an additional random delay based on this factor is added, e.g. `0.2` adds up to `20%` delay. In order to skip this additional delay pass in `0`.</param>
-        /// <param name="strategy">The supervision strategy to use for handling exceptions in the child</param>
+        /// <param name="strategy">The supervision strategy used to handle child failures. For a <see cref="OneForOneStrategy"/>, its retry limit also caps the backoff restart count.</param>
+        /// <returns>Props configured to create a <see cref="BackoffSupervisor"/>.</returns>
         public static Props PropsWithSupervisorStrategy(
             Props childProps,
             string childName,

src/core/Akka/Serialization/Serializer.cs

@@ -21,21 +21,14 @@ namespace Akka.Serialization
     /// <summary>
     /// A Serializer represents a bimap between an object and an array of bytes representing that object.
     ///
-    /// Serializers are loaded using reflection during <see cref="ActorSystem"/>
-    /// start-up, where two constructors are tried in order:
-    ///
-    /// <ul>
-    /// <li>taking exactly one argument of type <see cref="ExtendedActorSystem"/>;
-    /// this should be the preferred one because all reflective loading of classes
-    /// during deserialization should use ExtendedActorSystem.dynamicAccess (see
-    /// [[akka.actor.DynamicAccess]]), and</li>
-    /// <li>without arguments, which is only an option if the serializer does not
-    /// load classes using reflection.</li>
-    /// </ul>
-    ///
-    /// <b>Be sure to always use the PropertyManager for loading classes!</b> This is necessary to
-    /// avoid strange match errors and inequalities which arise from different class loaders loading
-    /// the same class.
+    /// When dynamic type loading is enabled, a custom serializer named by type in
+    /// <c>akka.actor.serializers</c> is created during serialization initialization. When
+    /// <c>akka.actor.serialization-settings.&lt;alias&gt;</c>
+    /// contains configuration, the loader invokes a constructor taking <see cref="ExtendedActorSystem"/>
+    /// and <see cref="Config"/>; otherwise it invokes a constructor taking only
+    /// <see cref="ExtendedActorSystem"/>. There is no parameterless-constructor fallback.
+    /// <see cref="SerializationSetup"/> registers serializer instances returned by its factory,
+    /// and those registrations are applied after the HOCON serializer entries.
     /// </summary>
     public abstract class Serializer
     {