Merge pull request #16668 from meln1k/wip-16614-include-best-practice-tip-on-messages-in-companion-object-in-docs-meln1k

=doc #16614 Include best-practice tip on messages in companion object in docs

akka-docs/rst/java/code/docs/actor/UntypedActorDocTest.java

@@ -535,6 +535,31 @@ public class UntypedActorDocTest {
     //#props-factory
   }
 
+  static
+  //#messages-in-companion
+  public class DemoMessagesActor extends UntypedActor {
+
+    static public class Greeting {
+      private final String from;
+
+      public Greeting(String from) {
+        this.from = from;
+      }
+
+      public String getGreeter() {
+        return from;
+      }
+    }
+
+    public void onReceive(Object message) throws Exception {
+      if (message instanceof Greeting) {
+        getSender().tell("Hello " + ((Greeting) message).getGreeter(), getSelf());
+      } else
+        unhandled(message);
+    }
+  }
+  //#messages-in-companion
+
   public static class MyActor extends UntypedActor {
 
     final String s;

akka-docs/rst/java/lambda-actors.rst

@@ -130,6 +130,13 @@ a reference to its enclosing scope:
 
 .. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java#props-factory
 
+Another good practice is to declare what messages an Actor can receive
+as close to the actor definition as possible (e.g. as static classes
+inside the Actor or using other suitable class), which makes it easier to know
+what it can receive.
+
+.. includecode:: ../../../akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java#messages-in-companion
+
 Creating Actors with Props
 --------------------------
 

akka-docs/rst/java/untyped-actors.rst

@@ -84,6 +84,13 @@ used constructor actually exists instead relying only on a runtime check.
 
 .. includecode:: code/docs/actor/UntypedActorDocTest.java#props-factory
 
+Another good practice is to declare what messages an Actor can receive
+as close to the actor definition as possible (e.g. as static classes
+inside the Actor or using other suitable class), which makes it easier to know
+what it can receive.
+
+.. includecode:: code/docs/actor/UntypedActorDocTest.java#messages-in-companion
+
 Creating Actors with Props
 --------------------------
 

akka-docs/rst/scala/actors.rst

@@ -120,6 +120,12 @@ a reference to its enclosing scope:
 
 .. includecode:: code/docs/actor/ActorDocSpec.scala#props-factory
 
+Another good practice is to declare what messages an Actor can receive
+in the companion object of the Actor, which makes easier
+to know what it can receive:
+
+.. includecode:: code/docs/actor/ActorDocSpec.scala#messages-in-companion
+
 Creating Actors with Props
 --------------------------
 

akka-docs/rst/scala/code/docs/actor/ActorDocSpec.scala

@@ -82,6 +82,24 @@ class DemoActorWrapper extends Actor {
   def receive = Actor.emptyBehavior
 }
 
+class ActorWithMessagesWrapper {
+  //#messages-in-companion
+  object MyActor {
+    case class Greeting(from: String)
+    case object Goodbye
+  }
+  class MyActor extends Actor with ActorLogging {
+    import MyActor._
+    def receive = {
+      case Greeting(greeter) => log.info(s"I was greeted by $greeter.")
+      case Goodbye => log.info("Someone said goodbye to me.")
+    }
+  }
+  //#messages-in-companion
+
+  def receive = Actor.emptyBehavior
+}
+
 class Hook extends Actor {
   var child: ActorRef = _
   //#preStart

akka-samples/akka-docs-java-lambda/src/test/java/docs/actor/ActorDocTest.java

@@ -152,6 +152,32 @@ public class ActorDocTest {
   }
   //#props-factory
 
+  static
+  //#messages-in-companion
+  public class DemoMessagesActor extends AbstractActor {
+
+    static public class Greeting {
+      private final String from;
+
+      public Greeting(String from) {
+        this.from = from;
+      }
+
+      public String getGreeter() {
+        return from;
+      }
+    }
+
+    DemoMessagesActor() {
+      receive(ReceiveBuilder.
+        match(Greeting.class, g -> {
+          log.info("I was greeted by {}", g.getGreeter());
+        }).build()
+      );
+    };
+  }
+  //#messages-in-companion
+
   public static class Hook extends AbstractActor {
     ActorRef target = null;
     public Hook() {