docs: improve docs (#14)

README.md

@@ -6,8 +6,8 @@
 
 Test your package against different versions of its dependencies.
 
-Generates and maintains multiple lockfiles so that you can test your package
-against different variations of your dependencies versions.
+Generates and maintains multiple lockfiles based on your defined variations (a.k.a. blends)
+so that you can test your package against different variations of your dependencies versions.
 
 ## Installation
 
@@ -32,6 +32,11 @@ $ mix blend.init
 
 ### 2. Define your blends
 
+Edit and set your blends in the `blend.exs` file.
+
+For example, an elixir package that depends on `plug_crypto` with a requirement of `~> 1.2 or ~> 2.0`,
+that wants to test against the two major versions, would want to define the following:
+
 ```elixir
 # blend.exs
 
@@ -42,8 +47,11 @@ $ mix blend.init
 }
 ```
 
-Edit and set your blends in the auto-generated `blend.exs` file.
+in order for blend to generate two different lockfiles that lock `plug_crypto` in each of the
+supported major versions.
 
+Map keys define the blend name, used for naming the lockfile, and the dependencies list are
+merged with the package dependencies before resolving and generating the lockfile variation.
 
 ### 3. Resolve blends and generate lockfiles
 

lib/blend.ex

@@ -1,7 +1,5 @@
 defmodule Blend do
-  @moduledoc """
-  Documentation for `Blend`.
-  """
+  @moduledoc false
 
   @blend_dir "blend"
   @blendfile_name "blend.exs"

lib/mix/tasks/blend/clean.ex

@@ -1,7 +1,13 @@
 defmodule Mix.Tasks.Blend.Clean do
+  @shortdoc "Cleans blend build artifacts"
+
+  @moduledoc """
+  A task to clean any stale lockfiles and blend build artifacts under the
+  `blend/` folder.
+  """
+
   use Mix.Task
 
-  @shortdoc "Cleans blend build artifacts"
   @requirements ["app.config"]
 
   @impl true

lib/mix/tasks/blend/get.ex

@@ -1,7 +1,16 @@
 defmodule Mix.Tasks.Blend.Get do
+  @shortdoc "Generates lockfiles from blend.exs"
+
+  @moduledoc """
+  A task to resolve your blends and generate lockfiles.
+
+  That is to say, have blend read your defined blends in `blend.exs` and generate
+  a lockfile for each blend by combining each specific blend overrides with your package
+  dependencies in `mix.exs`.
+  """
+
   use Mix.Task
 
-  @shortdoc "Generates lockfiles from blend.exs"
   @requirements ["app.config"]
 
   @impl true

lib/mix/tasks/blend/init.ex

@@ -1,8 +1,20 @@
 defmodule Mix.Tasks.Blend.Init do
-  use Mix.Task
-
   @shortdoc "Initializes an empty blend.exs file"
 
+  @moduledoc """
+  A task to generates an empty blend.exs file for you
+  to define your blends, if you don't yet have one.
+
+  It is created with a commented example in it.
+
+  ```
+  $ mix blend.init
+  Successfully created blend.exs file
+  ```
+  """
+
+  use Mix.Task
+
   @impl true
   def run(_args) do
     Blend.init()

lib/mix/tasks/blend/list.ex

@@ -1,8 +1,19 @@
 defmodule Mix.Tasks.Blend.List do
-  use Mix.Task
-
   @shortdoc "Lists blend names defined in blend.exs file"
 
+  @moduledoc """
+  A task to list to quickly get a list of blend names you have defined in
+  your blend.exs file.
+
+  ```
+  $ mix blend.list
+  plug_crypto_1
+  plug_crypto_2
+  ```
+  """
+
+  use Mix.Task
+
   @impl true
   def run(_args) do
     Blend.blends()

lib/mix/tasks/blend/premix.ex

@@ -1,8 +1,14 @@
 defmodule Mix.Tasks.Blend.Premix do
-  use Mix.Task
-
   @shortdoc "Generates premix.exs file"
 
+  @moduledoc """
+  Task to generate the `premix.exs` file, which helps confuguring your
+  package project to easily run any mix task against a specific blend
+  lockfile.
+  """
+
+  use Mix.Task
+
   @impl true
   def run(_args) do
     Blend.premix()

lib/mix/tasks/blend/update.ex

@@ -1,7 +1,15 @@
 defmodule Mix.Tasks.Blend.Update do
+  @shortdoc "Updates lockfiles from blend.exs"
+
+  @moduledoc """
+  A task to update your blend lockfiles dependencies.
+
+  That means, trying to get all the dependencies in each lockfile to their most recent
+  version possible respecting the defined version constraints.
+  """
+
   use Mix.Task
 
-  @shortdoc "Updates lockfiles from blend.exs"
   @requirements ["app.config"]
 
   @impl true

mix.exs

@@ -12,7 +12,12 @@ defmodule Blend.MixProject do
       elixir: "~> 1.13",
       start_permanent: Mix.env() == :prod,
       deps: deps(),
-      package: package()
+      package: package(),
+
+      # Docs
+      name: "Blend",
+      source_url: @source_url,
+      docs: docs()
     ]
   end
 
@@ -38,4 +43,10 @@ defmodule Blend.MixProject do
       }
     ]
   end
+
+  defp docs do
+    [
+      extras: ["README.md"]
+    ]
+  end
 end