Make the exit conditions for GenServer/GenEvent/Supervisor clear

Author: José Valim

lib/elixir/lib/gen_event.ex

@@ -227,6 +227,10 @@ defmodule GenEvent do
   returns `{:ok, pid}`, where pid is the pid of the server. If there already
   exists a process with the specified server name, the function returns
   `{:error, {:already_started, pid}}` with the pid of that process.
+
+  Note that a `GenEvent` started with `start_link/1` is linked to the
+  parent process and will exit not only on crashes but also if the parent
+  process exits with `:normal` reason.
   """
   @spec start_link(options) :: on_start
   def start_link(options \\ []) when is_list(options) do

lib/elixir/lib/gen_server.ex

@@ -269,6 +269,11 @@ defmodule GenServer do
   passing the given `args` to initialize it. To ensure a synchronized start-up
   procedure, this function does not return until `init/1` has returned.
 
+  Note that a `GenServer` started with `start_link/3` is linked to the
+  parent process and will exit in case of crashes. The GenServer will also
+  exit due to the `:normal` reasons in case it is configured to trap exits
+  in the `init/1` callback.
+
   ## Options
 
   The `:name` option is used for name registration as described in the module

lib/elixir/lib/supervisor.ex

@@ -195,6 +195,10 @@ defmodule Supervisor do
   an erroneous value, the supervisor will first terminate all already
   started child processes with reason `:shutdown` and then terminate
   itself and return `{:error, {:shutdown, reason}}`.
+
+  Note that the `Supervisor` is linked to the parent process
+  and will exit not only on crashes but also if the parent process
+  exits with `:normal` reason.
   """
   @spec start_link([tuple], options) :: on_start
   def start_link(children, options) when is_list(children) do