Add some docs

Author: ericmj

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,25 +29,43 @@ 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),
     do: {app, req, []}
   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: %{},

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

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

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