incorporate Viktor’s review

akka-actor-migration/src/main/scala/akka/migration/AskableActorRef.scala

@@ -7,7 +7,10 @@ import akka.actor.ActorRef
 import akka.dispatch.Future
 import akka.util.Timeout
 
-class AskableActorRef(val actorRef: ActorRef) {
+/**
+ * Implementation detail of the “ask” pattern enrichment of ActorRef
+ */
+private[akka] final class AskableActorRef(val actorRef: ActorRef) {
 
   /**
    * Sends a message asynchronously and returns a [[akka.dispatch.Future]]
@@ -29,8 +32,8 @@ class AskableActorRef(val actorRef: ActorRef) {
    * <b>Recommended usage:</b>
    *
    * {{{
-   *   val f = worker.ask(request)(timeout)
    *   flow {
+   *     val f = worker.ask(request)(timeout)
    *     EnrichedRequest(request, f())
    *   } pipeTo nextActor
    * }}}
@@ -59,8 +62,8 @@ class AskableActorRef(val actorRef: ActorRef) {
    * <b>Recommended usage:</b>
    *
    * {{{
-   *   val f = worker ? request
    *   flow {
+   *     val f = worker ? request
    *     EnrichedRequest(request, f())
    *   } pipeTo nextActor
    * }}}
@@ -69,6 +72,9 @@ class AskableActorRef(val actorRef: ActorRef) {
    */
   def ?(message: Any)(implicit timeout: Timeout): Future[Any] = akka.pattern.ask(actorRef, message)(timeout)
 
+  /**
+   * This method is just there to catch 2.0-unsupported usage and print deprecation warnings for it.
+   */
   @deprecated("use ?(msg)(timeout), this method has dangerous ambiguity", "2.0-migration")
   def ?(message: Any, timeout: Timeout)(i: Int = 0): Future[Any] = this.?(message)(timeout)
 }

akka-actor/src/main/scala/akka/actor/ActorRef.scala

@@ -355,7 +355,7 @@ case class SerializedActorRef(path: String) {
 /**
  * Trait for ActorRef implementations where all methods contain default stubs.
  */
-trait MinimalActorRef extends InternalActorRef with LocalRef {
+private[akka] trait MinimalActorRef extends InternalActorRef with LocalRef {
 
   def getParent: InternalActorRef = Nobody
 
@@ -381,7 +381,7 @@ trait MinimalActorRef extends InternalActorRef with LocalRef {
   protected def writeReplace(): AnyRef = SerializedActorRef(path.toString)
 }
 
-object MinimalActorRef {
+private[akka] object MinimalActorRef {
   def apply(_path: ActorPath, _provider: ActorRefProvider)(receive: PartialFunction[Any, Unit]): ActorRef = new MinimalActorRef {
     def path = _path
     def provider = _provider
@@ -392,7 +392,7 @@ object MinimalActorRef {
 
 case class DeadLetter(message: Any, sender: ActorRef, recipient: ActorRef)
 
-object DeadLetterActorRef {
+private[akka] object DeadLetterActorRef {
   class SerializedDeadLetterActorRef extends Serializable { //TODO implement as Protobuf for performance?
     @throws(classOf[java.io.ObjectStreamException])
     private def readResolve(): AnyRef = Serialization.currentSystem.value.deadLetters
@@ -401,7 +401,7 @@ object DeadLetterActorRef {
   val serialized = new SerializedDeadLetterActorRef
 }
 
-trait DeadLetterActorRefLike extends MinimalActorRef {
+private[akka] trait DeadLetterActorRefLike extends MinimalActorRef {
 
   def eventStream: EventStream
 
@@ -427,11 +427,9 @@ trait DeadLetterActorRefLike extends MinimalActorRef {
     case d: DeadLetter ⇒ eventStream.publish(d)
     case _             ⇒ eventStream.publish(DeadLetter(message, sender, this))
   }
-
-  // FIXME reimplement behavior of brokenPromise on ask
 }
 
-class DeadLetterActorRef(val eventStream: EventStream) extends DeadLetterActorRefLike {
+private[akka] class DeadLetterActorRef(val eventStream: EventStream) extends DeadLetterActorRefLike {
   @throws(classOf[java.io.ObjectStreamException])
   override protected def writeReplace(): AnyRef = DeadLetterActorRef.serialized
 }
@@ -440,7 +438,7 @@ class DeadLetterActorRef(val eventStream: EventStream) extends DeadLetterActorRe
  * This special dead letter reference has a name: it is that which is returned
  * by a local look-up which is unsuccessful.
  */
-class EmptyLocalActorRef(
+private[akka] class EmptyLocalActorRef(
   val eventStream: EventStream,
   _provider: ActorRefProvider,
   _dispatcher: MessageDispatcher,
@@ -454,7 +452,10 @@ class EmptyLocalActorRef(
   }
 }
 
-class VirtualPathContainer(
+/**
+ * Internal implementation detail used for paths like “/temp”
+ */
+private[akka] class VirtualPathContainer(
   val provider: ActorRefProvider,
   val path: ActorPath,
   override val getParent: InternalActorRef,

akka-actor/src/main/scala/akka/actor/ActorRefProvider.scala

@@ -74,12 +74,12 @@ trait ActorRefProvider {
   /**
    * Registers an actorRef at a path returned by tempPath(); do NOT pass in any other path.
    */
-  def registerTempActor(actorRef: InternalActorRef, path: ActorPath)
+  def registerTempActor(actorRef: InternalActorRef, path: ActorPath): Unit
 
   /**
    * Unregister a temporary actor from the “/temp” path (i.e. obtained from tempPath()); do NOT pass in any other path.
    */
-  def unregisterTempActor(path: ActorPath)
+  def unregisterTempActor(path: ActorPath): Unit
 
   /**
    * Actor factory with create-only semantics: will create an actor as

akka-actor/src/main/scala/akka/actor/Locker.scala

@@ -9,7 +9,10 @@ import akka.util.duration._
 import java.util.concurrent.ConcurrentHashMap
 import akka.event.DeathWatch
 
-class Locker(
+/**
+ * Internal implementation detail for disposing of orphaned actors.
+ */
+private[akka] class Locker(
   scheduler: Scheduler,
   period: Duration,
   val provider: ActorRefProvider,

akka-actor/src/main/scala/akka/pattern/AskSupport.scala

@@ -19,9 +19,15 @@ class AskTimeoutException(message: String, cause: Throwable) extends TimeoutExce
   def this(message: String) = this(message, null: Throwable)
 }
 
+/**
+ * This object contains implementation details of the “ask” pattern.
+ */
 object AskSupport {
 
-  final class AskableActorRef(val actorRef: ActorRef) {
+  /**
+   * Implementation detail of the “ask” pattern enrichment of ActorRef
+   */
+  private[akka] final class AskableActorRef(val actorRef: ActorRef) {
 
     /**
      * Sends a message asynchronously and returns a [[akka.dispatch.Future]]
@@ -43,8 +49,8 @@ object AskSupport {
      * <b>Recommended usage:</b>
      *
      * {{{
-     *   val f = worker.ask(request)(timeout)
      *   flow {
+     *     val f = worker.ask(request)(timeout)
      *     EnrichedRequest(request, f())
      *   } pipeTo nextActor
      * }}}
@@ -73,8 +79,8 @@ object AskSupport {
      * <b>Recommended usage:</b>
      *
      * {{{
-     *   val f = worker ? request
      *   flow {
+     *     val f = worker ? request
      *     EnrichedRequest(request, f())
      *   } pipeTo nextActor
      * }}}