Add more docs and examples around function_exported?/3 and macro_exported?/3

Author: josevalim

lib/elixir/lib/kernel.ex

@@ -4515,26 +4515,32 @@ defmodule Kernel do
   Returns `true` if `module` is loaded and contains a
   public `function` with the given `arity`, otherwise `false`.
 
-  > ### Unloaded modules {: .warning } 
+  > ### Unloaded modules {: .warning}
   >
   > This function does *not* load the module in case it is not loaded
   > and Elixir lazily loads modules by default (except on releases).
-  > This may yield unexpected results in testing when module
-  > usage order is random.
+  >
+  > This may lead to unexpected behaviour as the result of this function
+  > may depend if another code has happened to load the given module
+  > as argument beforehand. For example, this could manifest in `mix test`
+  > by having tests that fail when running in isolation or depending on the
+  > test seed. For those reasons, it is recommended to always check for
+  > `Code.ensure_loaded?/1` before `function_exported?/3`, unless you are
+  > certain the module has been loaded before.
   >
   > See `Code.ensure_loaded/1` for more information.
 
   Inlined by the compiler.
 
   ## Examples
 
-      iex> function_exported?(Enum, :map, 2)
+      iex> Code.ensure_loaded?(Enum) and function_exported?(Enum, :map, 2)
       true
 
-      iex> function_exported?(Enum, :map, 10)
+      iex> Code.ensure_loaded?(Enum) and function_exported?(Enum, :map, 10)
       false
 
-      iex> function_exported?(List, :to_string, 1)
+      iex> Code.ensure_loaded?(List) and function_exported?(List, :to_string, 1)
       true
   """
   @spec function_exported?(module, atom, arity) :: boolean
@@ -4547,18 +4553,18 @@ defmodule Kernel do
   public `macro` with the given `arity`, otherwise `false`.
 
   Note that this function does not load the module in case
-  it is not loaded. Check `Code.ensure_loaded/1` for more
-  information.
+  it is not loaded. See the notes under `function_exported?/3`
+  for more information.
 
   If `module` is an Erlang module (as opposed to an Elixir module), this
   function always returns `false`.
 
   ## Examples
 
-      iex> macro_exported?(Kernel, :use, 2)
+      iex> Code.ensure_loaded?(Kernel) and macro_exported?(Kernel, :use, 2)
       true
 
-      iex> macro_exported?(:erlang, :abs, 1)
+      iex> Code.ensure_loaded?(:erlang) and macro_exported?(:erlang, :abs, 1)
       false
 
   """

lib/elixir/pages/references/typespecs.md

@@ -62,9 +62,13 @@ The notation to represent the union of types is the pipe `|`. For example, the t
 > #### Differences with set-theoretic types {: .warning}
 >
 > While they do share some similarities, the types below do not map one-to-one
-> to the new types from the set theoretic type system.
+> to the new types from the set-theoretic type system.
+>
 > For example, there is no plan to support subsets of the `integer()` type such
 > as positive, ranges or literals.
+>
+> Furthermore, set-theoretic types support the full range of set operations,
+> including intersections and negations.
 
 ### Basic types
 
@@ -388,10 +392,9 @@ Note you don't need to define a behaviour in order to dynamically dispatch on a
 
 Optional callbacks are callbacks that callback modules may implement if they want to, but are not required to. Usually, behaviour modules know if they should call those callbacks based on configuration, or they check if the callbacks are defined with `function_exported?/3` or `macro_exported?/3`.
 
-> Testing Optional Callbacks {: .warning }
+> ### Unloaded modules {: .warning}
 >
-> `mix test` may exhibit unexpected behaviour when testing a conditional call to an optional callback gated
-> on `function_exported?/3`, see the documentation on this function for details.
+> `function_exported?/3` (and `macro_exported?/3`) do *not* load the module in case it is not loaded and Elixir lazily loads modules by default (except on releases). So in practice you will want to invoke `Code.ensure_loaded?/1` before checking if the function/macro is exported. See the documentation for `function_exported?/3` for examples.
 
 Optional callbacks can be defined through the `@optional_callbacks` module attribute, which has to be a keyword list with function or macro name as key and arity as value. For example: