Document Subscription Demand in BroadcastDispatcher

lib/gen_stage/dispatchers/broadcast_dispatcher.ex

@@ -1,5 +1,5 @@
 defmodule GenStage.BroadcastDispatcher do
-  @moduledoc """
+  @moduledoc ~S"""
   A dispatcher that accumulates demand from all consumers
   before broadcasting events to all of them.
 
@@ -29,6 +29,27 @@ defmodule GenStage.BroadcastDispatcher do
           [{producer, selector: fn %{key: key} -> String.starts_with?(key, "foo-") end}]}
       end
 
+  ## Demand while Setup
+
+  ```
+                [Producer Consumer 1]
+               /                     \
+  [Producer] -                        - [Consumer]
+               \                     /
+                [Producer Consumer 2]
+  ```
+
+  When starting `Producer Consumer 1` before `Producer Consumer 2`, it is
+  possible that the first batch of events is only delivered to
+  `Producer Consumer 1` since `Producer Consummer 2` is not registered yet.
+  Since `producer_consumer` is buffering, it is irrelenvant if the `Consumer`
+  has not been started yet, the demand arises on start of the
+  `producer_consumer`. The more stages you register, the more likely it is that
+  you will miss events.
+
+  It is therefore recommended to start the consumers with an empty
+  `subscribe_to` option and create the subscriptions manually after all stages
+  were started using `GenStage.async_subscribe/2`.
   """
 
   @behaviour GenStage.Dispatcher