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
 --------------------------