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

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