improve ScalaDoc of actorOf methods (esp. their blocking on ActorSystem)

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

@@ -15,6 +15,31 @@ import akka.util.{ Duration, Helpers }
  * The actor context - the view of the actor cell from the actor.
  * Exposes contextual information for the actor and the current message.
  * TODO: everything here for current compatibility - could be limited more
+ * 
+ * There are several possibilities for creating actors (see [[akka.actor.Props]]
+ * for details on `props`):
+ * 
+ * {{{
+ * // Java or Scala
+ * context.actorOf(props, "name")
+ * context.actorOf(props)
+ * 
+ * // Scala
+ * context.actorOf[MyActor]("name")
+ * context.actorOf[MyActor]
+ * context.actorOf(new MyActor(...))
+ * 
+ * // Java
+ * context.actorOf(classOf[MyActor]);
+ * context.actorOf(new Creator<MyActor>() {
+ *   public MyActor create() { ... }
+ * });
+ * context.actorOf(new Creator<MyActor>() {
+ *   public MyActor create() { ... }
+ * }, "name");
+ * }}}
+ * 
+ * Where no name is given explicitly, one will be automatically generated.
  */
 trait ActorContext extends ActorRefFactory {
 

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

@@ -120,7 +120,8 @@ trait ActorRefProvider {
 }
 
 /**
- * Interface implemented by ActorSystem and AkkaContext, the only two places from which you can get fresh actors.
+ * Interface implemented by ActorSystem and AkkaContext, the only two places 
+ * from which you can get fresh actors.
  */
 trait ActorRefFactory {
 
@@ -143,6 +144,10 @@ trait ActorRefFactory {
    * reversed and with “$” prepended, may change in the future).
    *
    * See [[akka.actor.Props]] for details on how to obtain a `Props` object.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf(props: Props): ActorRef
 
@@ -152,6 +157,10 @@ trait ActorRefFactory {
    * and `InvalidActorNameException` is thrown.
    *
    * See [[akka.actor.Props]] for details on how to obtain a `Props` object.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf(props: Props, name: String): ActorRef
 
@@ -160,6 +169,10 @@ trait ActorRefFactory {
    * generated name (currently similar to base64-encoded integer count,
    * reversed and with “$” prepended, may change in the future). The type must have
    * a no-arg constructor which will be invoked using reflection.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf[T <: Actor](implicit m: Manifest[T]): ActorRef = actorOf(Props(m.erasure.asInstanceOf[Class[_ <: Actor]]))
 
@@ -168,6 +181,10 @@ trait ActorRefFactory {
    * not be null, empty or start with “$”. If the given name is already in use,
    * and `InvalidActorNameException` is thrown. The type must have
    * a no-arg constructor which will be invoked using reflection.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf[T <: Actor](name: String)(implicit m: Manifest[T]): ActorRef =
     actorOf(Props(m.erasure.asInstanceOf[Class[_ <: Actor]]), name)
@@ -177,6 +194,10 @@ trait ActorRefFactory {
    * generated name (currently similar to base64-encoded integer count,
    * reversed and with “$” prepended, may change in the future). The class must have
    * a no-arg constructor which will be invoked using reflection.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf[T <: Actor](clazz: Class[T]): ActorRef = actorOf(Props(clazz))
 
@@ -186,6 +207,10 @@ trait ActorRefFactory {
    * reversed and with “$” prepended, may change in the future). Use this
    * method to pass constructor arguments to the [[akka.actor.Actor]] while using
    * only default [[akka.actor.Props]]; otherwise refer to `actorOf(Props)`.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf(factory: ⇒ Actor): ActorRef = actorOf(Props(() ⇒ factory))
 
@@ -195,6 +220,10 @@ trait ActorRefFactory {
    * count, reversed and with “$” prepended, may change in the future).
    *
    * Identical to `actorOf(Props(() => creator.create()))`.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf(creator: UntypedActorFactory): ActorRef = actorOf(Props(() ⇒ creator.create()))
 
@@ -204,6 +233,10 @@ trait ActorRefFactory {
    * and `InvalidActorNameException` is thrown.
    *
    * Identical to `actorOf(Props(() => creator.create()), name)`.
+   *
+   * When invoked on ActorSystem, this method sends a message to the guardian
+   * actor and blocks waiting for a reply, see `akka.actor.creation-timeout` in
+   * the `reference.conf`.
    */
   def actorOf(creator: UntypedActorFactory, name: String): ActorRef = actorOf(Props(() ⇒ creator.create()), name)
 

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

@@ -158,6 +158,31 @@ object ActorSystem {
  * An actor system is a hierarchical group of actors which share common
  * configuration, e.g. dispatchers, deployments, remote capabilities and
  * addresses. It is also the entry point for creating or looking up actors.
+ * 
+ * There are several possibilities for creating actors (see [[akka.actor.Props]]
+ * for details on `props`):
+ * 
+ * {{{
+ * // Java or Scala
+ * system.actorOf(props, "name")
+ * system.actorOf(props)
+ * 
+ * // Scala
+ * system.actorOf[MyActor]("name")
+ * system.actorOf[MyActor]
+ * system.actorOf(new MyActor(...))
+ * 
+ * // Java
+ * system.actorOf(classOf[MyActor]);
+ * system.actorOf(new Creator<MyActor>() {
+ *   public MyActor create() { ... }
+ * });
+ * system.actorOf(new Creator<MyActor>() {
+ *   public MyActor create() { ... }
+ * }, "name");
+ * }}}
+ * 
+ * Where no name is given explicitly, one will be automatically generated.
  */
 abstract class ActorSystem extends ActorRefFactory {
   import ActorSystem._