Clarify attributes and exit signals in the language

Author: José Valim

lib/elixir/lib/kernel.ex

@@ -183,9 +183,56 @@ defmodule Kernel do
 
   ## Examples
 
+  When a process reaches its end, by default it exits with
+  reason `:normal`. You can also call it explicitly if you
+  want to terminate a process but not signal any failure:
+
       exit(:normal)
+
+  In case something goes wrong, you can also use `exit/1` with
+  a different reason:
+
       exit(:seems_bad)
 
+  If the reason is not `:normal`, all linked process to the
+  exited process will crash (unless they are trapping exits).
+
+  ## OTP exits
+
+  Exits are used by OTP to determine if a process exited abnormally
+  or not. The following exits are considered "normal":
+
+    * `exit(:normal)`
+    * `exit(:shutdown)`
+    * `exit({:shutdown, term})`
+
+  Exiting with any other reason is considered abnormal and treated
+  as a crash. This means the default supervisor behaviour kicks in,
+  error reports are emitted, etc.
+
+  This behaviour is relied on in many different places. For example,
+  `ExUnit` uses `exit(:shutdown)` when exiting the test process to
+  signal linked processes, supervision trees and so on to politely
+  shutdown too.
+
+  ## CLI exits
+
+  Building on top of the exit signals mentioned above, if the
+  process started by the command line exits with any of the three
+  reasons above, its exit is considered normal and the Operating
+  System process will exit with status 0.
+
+  It is, however, possible to customize the Operating System exit
+  signal by invoking:
+
+      exit({:shutdown, integer})
+
+  This will cause the OS process to exit with the status given by
+  `integer` while signaling all linked OTP processes to politely
+  shutdown.
+
+  Any other exit reason will cause the OS process to exit with
+  status `1` and linked OTP processes to crash.
   """
   @spec exit(term) :: no_return
   def exit(reason) do

lib/elixir/lib/module.ex

@@ -766,15 +766,9 @@ defmodule Module do
 
       @foo
 
-  Expands to:
+  Expands close to:
 
-      Module.get_attribute(__MODULE__, :foo, [{Module, :func, 0, [file: "module.ex", line: 1]}])
-
-  Notice the third argument may be given to indicate a stacktrace
-  to be emitted when the attribute was not previously defined.
-  The default value for `warn` is nil for direct calls but the `@foo`
-  macro sets it to the proper stacktrace automatically, warning
-  every time `@foo` is used but not set previously.
+      Module.get_attribute(__MODULE__, :foo)
 
   ## Examples
 
@@ -788,37 +782,9 @@ defmodule Module do
       end
 
   """
-  @spec get_attribute(module, atom, warn :: nil | [tuple]) :: term
-  def get_attribute(module, key, warn \\ nil) when
-      is_atom(key) and (is_list(warn) or nil?(warn)) do
-    assert_not_compiled!(:get_attribute, module)
-    table = data_table_for(module)
-
-    case :ets.lookup(table, key) do
-      [{^key, val}] -> val
-      [] ->
-        acc = :ets.lookup_element(table, :__acc_attributes, 2)
-
-        cond do
-          :lists.member(key, acc) ->
-            []
-          is_list(warn) ->
-            :elixir_errors.warn warn_info(warn), "undefined module attribute @#{key}, " <>
-              "please remove access to @#{key} or explicitly set it to nil before access"
-            nil
-          true ->
-            nil
-        end
-    end
-  end
-
-  defp warn_info([entry|_]) do
-    opts = elem(entry, tuple_size(entry) - 1)
-    Exception.format_file_line(Keyword.get(opts, :file), Keyword.get(opts, :line)) <> " "
-  end
-
-  defp warn_info([]) do
-    ""
+  @spec get_attribute(atom, atom) :: term
+  def get_attribute(module, key) do
+    get_attribute(module, key, nil)
   end
 
   @doc """
@@ -832,10 +798,12 @@ defmodule Module do
       end
 
   """
+  @spec delete_attribute(atom, atom) :: :ok
   def delete_attribute(module, key) when is_atom(key) do
     assert_not_compiled!(:delete_attribute, module)
     table = data_table_for(module)
     :ets.delete(table, key)
+    :ok
   end
 
   @doc """
@@ -935,6 +903,38 @@ defmodule Module do
     :ets.insert(table, {key, new})
   end
 
+  @doc false
+  def get_attribute(module, key, warn) when is_atom(key) and (is_list(warn) or nil?(warn)) do
+    assert_not_compiled!(:get_attribute, module)
+    table = data_table_for(module)
+
+    case :ets.lookup(table, key) do
+      [{^key, val}] -> val
+      [] ->
+        acc = :ets.lookup_element(table, :__acc_attributes, 2)
+
+        cond do
+          :lists.member(key, acc) ->
+            []
+          is_list(warn) ->
+            :elixir_errors.warn warn_info(warn), "undefined module attribute @#{key}, " <>
+              "please remove access to @#{key} or explicitly set it to nil before access"
+            nil
+          true ->
+            nil
+        end
+    end
+  end
+
+  defp warn_info([entry|_]) do
+    opts = elem(entry, tuple_size(entry) - 1)
+    Exception.format_file_line(Keyword.get(opts, :file), Keyword.get(opts, :line)) <> " "
+  end
+
+  defp warn_info([]) do
+    ""
+  end
+
   ## Helpers
 
   defp normalize_attribute(:on_load, atom) when is_atom(atom) do