   // ==== ---------------------------------------------------------------------
   // - MARK: Resolving actors by identity
 
-  /// Resolve a local or remote actor address to a real actor instance, or throw if unable to.
+  /// Resolves a local or remote ``ActorID`` to a reference to given actor, or throws if unable to.
+  ///
   /// The returned value is either a local actor or proxy to a remote actor.
   ///
-  /// Resolving an actor is called when a specific distributed actors `init(from:)`
-  /// decoding initializer is invoked. Once the actor's identity is deserialized
-  /// using the `decodeIdentity(from:)` call, it is fed into this function, which
-  /// is responsible for resolving the identity to a remote or local actor reference.
-  ///
-  /// If the resolve fails, meaning that it cannot locate a local actor managed for
-  /// this identity, managed by this transport, nor can a remote actor reference
-  /// be created for this identity on this transport, then this function must throw.
+  /// This function is not intended to be used directly, but instead is called by the Swift runtime
+  /// whenever ``DistributedActor/resolve(id:using:)` or  a concrete distributed actor's `init(from:)` is invoked.
+  ///
+  /// This function should either return an existing actor reference, or `nil` to signal that a remote distributed actor
+  /// "proxy" should be created for this ``ActorID``. If the resolve fails, meaning that it can neither locate a local
+  /// actor managed by this actor system, nor identify that the identity is located on some remote actor system, then
+  /// this function should throw.
+  ///
+  /// ```swift
+  /// distributed actor Worker { /* ... */ }
+  ///
+  /// // the following internally calls actorSystem.resolve(id: id, as: Worker.self)
+  /// let worker: Worker = try  Worker.resolve(id: id, using: actorSystem)
+  /// ```
   ///
   /// If this function returns correctly, the returned actor reference is immediately
   /// usable. It may not necessarily imply the strict *existence* of a remote actor


/// Decoder that must be provided to `executeDistributedTarget` and is used
/// by the Swift runtime to decode arguments of the invocation.
@available(SwiftStdlib 5.7, *)
public protocol DistributedTargetInvocationDecoder {
  associatedtype SerializationRequirement

  mutating func decodeGenericSubstitutions() throws -> [Any.Type]

//  /// Ad-hoc protocol requirement

  /// mapping for the purpose of implementing the `resolve(id:as:)` method.
  ///
  /// The system usually should NOT retain the passed reference, and it will be informed via
  /// ``resignID(_:)`` when the actor has been deallocated so it can remove the stale reference from its
  /// internal `ActorID: DistributedActor` mapping.
  ///
  /// The ``DistributedActor/id`` of the passed actor must be an ``ActorID`` that this system previously has assigned.
  ///
  /// If `actorReady` gets called with some unknown ID, it should crash immediately as it signifies some
  /// very unexpected use of the system.
