Update documentation for embedded listeners

1 files changed, 20 insertions, 21 deletions

diff --git a/doc/src/guide/embedded.asciidoc b/doc/src/guide/embedded.asciidoc
index 55c018b..28f567b 100644
--- a/doc/src/guide/embedded.asciidoc
+++ b/doc/src/guide/embedded.asciidoc
@@ -5,44 +5,43 @@ in your supervision tree. This allows for greater fault tolerance
 control by permitting the shutdown of a listener due to the
 failure of another part of the application and vice versa.
 
+However, just as for non-embedded listeners that were started via
+`ranch:start_listener/5`, it is required that the `ranch` application
+is running before you can start embedded listeners. Furthermore,
+this also means that embedded listeners will restart when `ranch_sup` fails.
+
+WARNING: By using embedded mode, it is possible to start a listener with the same name
+as an already existing listener. This will corrupt the information Ranch
+keeps for that listener, so you should take care to ensure unique listener
+names yourself. A good way to achieve this is by combining the embedded
+listener's name with `?MODULE`, or the name of the application it is used
+in.
+
 === Embedding
 
 To embed Ranch in your application you can simply add the child specs
 to your supervision tree. This can all be done in the `init/1` function
 of one of your application supervisors.
 
-Ranch requires at the minimum two kinds of child specs for embedding.
-First, you need to add `ranch_sup` to your supervision tree, only once,
-regardless of the number of listeners you will use. Then you need to
-add the child specs for each listener.
-
 Ranch has a convenience function for getting the listeners child specs
 called `ranch:child_spec/5`, that works like `ranch:start_listener/5`,
 except that it doesn't start anything, it only returns child specs.
 
-As for `ranch_sup`, the child spec is simple enough to not require a
-convenience function.
-
-The following example adds both `ranch_sup` and one listener to another
-application's supervision tree.
+The following example adds one listener to another application's
+supervision tree.
 
 .Embed Ranch directly in your supervision tree
 
 [source,erlang]
 ----
 init([]) ->
-	RanchSupSpec = {ranch_sup, {ranch_sup, start_link, []},
-		permanent, 5000, supervisor, [ranch_sup]},
-	ListenerSpec = ranch:child_spec(echo, 100,
-		ranch_tcp, [{port, 5555}],
+	ListenerSpec = ranch:child_spec({?MODULE, echo},
+		ranch_tcp, #{socket_opts => [{port, 5555}]},
 		echo_protocol, []
 	),
-	{ok, {{one_for_one, 10, 10}, [RanchSupSpec, ListenerSpec]}}.
+	{ok, {#{}, [ListenerSpec]}}.
 ----
 
-Remember, you can add as many listener child specs as needed, but only
-one `ranch_sup` spec!
-
-It is recommended that your architecture makes sure that all listeners
-are restarted if `ranch_sup` fails. See the Ranch internals chapter for
-more details on how Ranch does it.
+Embedded listeners cannot be stopped via `ranch:stop_listener/1`. Instead,
+are to be stopped as part of the shutdown of your application's supervison
+tree.