From 6188babe3a5fc10ededde695503e6972be6cbfef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Eric=20Meadows-J=C3=B6nsson?=
 <eric.meadows.jonsson@gmail.com>
Date: Sun, 31 Aug 2014 23:51:25 +0200
Subject: [PATCH] Add some docs

---
 lib/hex/mix.ex              | 34 ++++++++++++++++++++++++++++++++++
 lib/hex/parallel.ex         | 11 +++++++++++
 lib/hex/remote_converger.ex |  2 +-
 lib/hex/resolver.ex         |  4 ++--
 4 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/lib/hex/mix.ex b/lib/hex/mix.ex
index 8494c991e..3a8671c26 100644
--- a/lib/hex/mix.ex
+++ b/lib/hex/mix.ex
@@ -1,7 +1,23 @@
 defmodule Hex.Mix do
+  @moduledoc """
+  Utility functions around Mix dependencies.
+  """
+
+  @doc """
+  Returns `true` if the version and requirement match.
+
+  See `Version.match?/2`.
+  """
+  @spec version_match?(String.t, String.t) :: boolean
   def version_match?(_version, nil), do: true
   def version_match?(version, req),  do: Version.match?(version, req)
 
+  @doc """
+  Converts a list of dependencies to a requests to the resolver. Skips
+  dependencies overriding with another SCM (but include dependencies
+  overriding with Hex) and dependencies that are not Hex packages.
+  """
+  @spec deps_to_requests([Mix.Dep.t]) :: [{String.t, String.t}]
   def deps_to_requests(deps) do
     overridden =
       for %Mix.Dep{app: app, scm: scm, opts: opts} <- deps,
@@ -13,12 +29,20 @@ defmodule Hex.Mix do
         do: {"#{app}", req}
   end
 
+  @doc """
+  Returns the names of all given overriding dependencies.
+  """
+  @spec deps_to_overridden([Mix.Dep.t]) :: [String.t]
   def deps_to_overridden(deps) do
     for %Mix.Dep{app: app, top_level: true, opts: opts} <- deps,
         opts[:override],
         do: "#{app}"
   end
 
+  @doc """
+  Normalises a dependency definition to its 3-tuple form.
+  """
+  @spec dep(tuple) :: {String.t, String.t, Keyword.t}
   def dep({app, opts}) when is_list(opts),
     do: {app, nil, opts}
   def dep({app, req}) when is_binary(req),
@@ -26,12 +50,22 @@ defmodule Hex.Mix do
   def dep({app, req, opts}),
     do: {app, req, opts}
 
+  @doc """
+  Takes all Hex packages from the lock and returns them
+  as `{name, version}` tuples.
+  """
+  @spec from_lock(%{}) :: %{}
   def from_lock(lock) do
     for {name, {:package, version}} <- lock,
         into: %{},
         do: {"#{name}", version}
   end
 
+  @doc """
+  Takes a map of `{name, version}` and returns them as a
+  lock of Hex packages.
+  """
+  @spec to_lock(%{}) :: %{}
   def to_lock(result) do
     for {name, version} <- result,
         into: %{},
diff --git a/lib/hex/parallel.ex b/lib/hex/parallel.ex
index 2995935f1..5dc11e6ca 100644
--- a/lib/hex/parallel.ex
+++ b/lib/hex/parallel.ex
@@ -1,14 +1,25 @@
 defmodule Hex.Parallel do
+  @moduledoc """
+  Run a number of jobs (with an upper bound) in parallel and
+  await their finish.
+  """
+
   use GenServer
 
   def start_link(name, opts) do
     GenServer.start_link(__MODULE__, new_state(opts), name: name)
   end
 
+  @doc """
+  """
+  @spec run(GenServer.server, any, (() -> any)) :: :ok
   def run(name, id, fun) do
     GenServer.cast(name, {:run, id, fun})
   end
 
+  @doc """
+  """
+  @spec await(GenServer.server, timeout) :: any
   def await(name, id, timeout \\ :infinity) do
     GenServer.call(name, {:await, id}, timeout)
   end
diff --git a/lib/hex/remote_converger.ex b/lib/hex/remote_converger.ex
index ba2cdea4e..280ea67fa 100644
--- a/lib/hex/remote_converger.ex
+++ b/lib/hex/remote_converger.ex
@@ -143,7 +143,7 @@ defmodule Hex.RemoteConverger do
     # Remove dependencies from the lock if:
     # 1. They are defined as git or path in mix.exs
     # 2. If the requirement in mix.exs does not match the locked version
-    # 3. If it's a child of another Hex package
+    # 3. If it's a child of another Hex package being updated
 
     unlock =
       Enum.flat_map(deps, fn
diff --git a/lib/hex/resolver.ex b/lib/hex/resolver.ex
index 8f471a5e5..6b79fb7e5 100644
--- a/lib/hex/resolver.ex
+++ b/lib/hex/resolver.ex
@@ -25,8 +25,8 @@ defmodule Hex.Resolver do
   end
 
   defp locked({name, version}, {activated, pending, optional}, info) do
-    # Make sure to add children of locked dependencies, they may have been
-    # overridden before and not been included in the lock
+    # Make sure to add children of locked dependencies, they may be missing
+    # from the lock for multiple reasons
 
     {new_pending, new_optional} = get_deps(name, version, info)
     pending = pending ++ new_pending