Add comments to public functions

2 files changed, 47 insertions, 2 deletions

diff --git a/lib/elixir/lib/module/types/helpers.ex b/lib/elixir/lib/module/types/helpers.ex
index 15ed2dfaa..baa685ba4 100644
--- a/lib/elixir/lib/module/types/helpers.ex
+++ b/lib/elixir/lib/module/types/helpers.ex
@@ -1,8 +1,12 @@
 defmodule Module.Types.Helpers do
   @moduledoc false
 
-  # Push expr to stack inside fun and pop after fun
-  # The expression stack is used for
+  @doc """
+  Push expr to stack inside fun and pop after fun.
+
+  The expression stack is used to give the context where a type variable
+  was refined when show a type conflict error.
+  """
   def expr_stack(expr, context, fun) do
     expr_stack = context.expr_stack
 
@@ -13,6 +17,10 @@ defmodule Module.Types.Helpers do
     end
   end
 
+  @doc """
+  Like `Enum.reduce/3` but only continues while `fun` returns `{:ok, acc}`
+  and stops on `{:error, reason}`.
+  """
   def reduce_ok(list, acc, fun) do
     do_reduce_ok(list, acc, fun)
   end
@@ -33,6 +41,10 @@ defmodule Module.Types.Helpers do
 
   defp do_reduce_ok([], acc, _fun), do: {:ok, acc}
 
+  @doc """
+  Like `Enum.unzip/1` but only continues while `fun` returns `{:ok, elem1, elem2}`
+  and stops on `{:error, reason}`.
+  """
   def unzip_ok(list) do
     do_unzip_ok(list, [], [])
   end
@@ -45,6 +57,10 @@ defmodule Module.Types.Helpers do
 
   defp do_unzip_ok([], acc1, acc2), do: {:ok, Enum.reverse(acc1), Enum.reverse(acc2)}
 
+  @doc """
+  Like `Enum.map/2` but only continues while `fun` returns `{:ok, elem}`
+  and stops on `{:error, reason}`.
+  """
   def map_ok(list, fun) do
     do_map_ok(list, [], fun)
   end
@@ -65,6 +81,10 @@ defmodule Module.Types.Helpers do
 
   defp do_map_ok([], acc, _fun), do: {:ok, Enum.reverse(acc)}
 
+  @doc """
+  Like `Enum.map_reduce/3` but only continues while `fun` returns `{:ok, elem, acc}`
+  and stops on `{:error, reason}`.
+  """
   def map_reduce_ok(list, acc, fun) do
     do_map_reduce_ok(list, {[], acc}, fun)
   end
diff --git a/lib/elixir/lib/module/types/infer.ex b/lib/elixir/lib/module/types/infer.ex
index 657f17238..a1cf377c9 100644
--- a/lib/elixir/lib/module/types/infer.ex
+++ b/lib/elixir/lib/module/types/infer.ex
@@ -14,6 +14,10 @@ defmodule Module.Types.Infer do
 
   ## PATTERNS
 
+  @doc """
+  Return the type and typing context of a pattern expression or an error
+  in case of a typing conflict.
+  """
   # :atom
   def of_pattern(atom, context) when is_atom(atom) do
     {:ok, {:literal, atom}, context}
@@ -163,6 +167,10 @@ defmodule Module.Types.Infer do
 
   ## GUARDS
 
+  @doc """
+  Refines the type variables in the typing context using type check guards
+  such as `is_integer/1`.
+  """
   def of_guard(guard, context) do
     expr_stack(guard, context, fn context ->
       # Flatten `foo and bar` to list of type constraints
@@ -296,6 +304,10 @@ defmodule Module.Types.Infer do
 
   ## UNIFICATION
 
+  @doc """
+  Unifies two types and returns the unified type and an updated typing context
+  or an error in case of a typing conflict.
+  """
   def unify(left, right, context) do
     case do_unify(left, right, context) do
       {:ok, type, context} -> {:ok, type, %{context | unify_stack: []}}
@@ -435,6 +447,10 @@ defmodule Module.Types.Infer do
     %{context | unify_stack: [var | context.unify_stack]}
   end
 
+  @doc """
+  Adds a variable to the typing context and returns its type variables.
+  If the variable has already been added, return the existing type variable.
+  """
   def new_var(var, context) do
     case :maps.find(var_name(var), context.vars) do
       {:ok, type} ->
@@ -512,6 +528,10 @@ defmodule Module.Types.Infer do
     false
   end
 
+  @doc """
+  Checks if the first argument is a subtype of the second argument.
+  Only checks for simple and concrete types.
+  """
   def subtype?({:literal, boolean}, :boolean, _context) when is_boolean(boolean), do: true
   def subtype?({:literal, atom}, :atom, _context) when is_atom(atom), do: true
   def subtype?(:boolean, :atom, _context), do: true
@@ -528,6 +548,11 @@ defmodule Module.Types.Infer do
 
   def subtype?(left, right, _context), do: left == right
 
+  @doc """
+  Returns a "simplified" union using `subtype?/3` to remove redundant
+  types. Due to limitations in `subtype?/3` some overlapping types
+  may still be included.
+  """
   def to_union(types, context) when types != [] do
     if :dynamic in types do
       :dynamic