Release v0.1.0

README.md

@@ -1,12 +1,9 @@
 # Odometex
+Simple distance comparisons for Elixir.
 
-**TODO: Add description**
+**Note:** Unit length -> meters
 
 ## Installation
-
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `odometex` to your list of dependencies in `mix.exs`:
-
 ```elixir
 def deps do
   [
@@ -15,7 +12,36 @@ def deps do
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at [https://hexdocs.pm/odometex](https://hexdocs.pm/odometex).
+## Usage
+To compare distances with some global references.
+```elixir
+  Odometex.compare(20)
+  # => [
+  #   %Odometex.Result{label: "Bowling lane", meters: 19, times: 1.052632},
+  #   %Odometex.Result{label: "Blue Whale (female)", meters: 25, times: 0.8},
+  #   %Odometex.Result{label: "Basketball court", meters: 28, times: 0.714286},
+  #   %Odometex.Result{label: "Football pitch", meters: 105, times: 0.190476},
+  #   %Odometex.Result{
+  #     label: "Passeig de Gràcia, Barcelona",
+  #     meters: 1300,
+  #     times: 0.015385
+  #   }
+  # ]
+
+  # It supports order and limit options
+  Odometex.compare(20, order: :desc, limit: 5)
+  # => [
+  #   %Odometex.Result{label: "Great Wall", meters: 8851000, times: 2.0e-6},
+  #   %Odometex.Result{label: "Amazon River", meters: 6992000, times: 3.0e-6},
+  #   %Odometex.Result{label: "Nile", meters: 6853000, times: 3.0e-6},
+  #   %Odometex.Result{label: "Sahara", meters: 4800000, times: 4.0e-6},
+  #   %Odometex.Result{label: "Route 66", meters: 3945000, times: 5.0e-6}
+  # ]
+```
+
+Documentation can be found on [HexDocs](https://hexdocs.pm/odometex/api-reference.html).
+
+## Contributing
+Do you know any cool distance/reference that isn't listed [here](config/distances.json)? It isn't also on the open issues?
+Please create a new issue or submit a PR, we will be happy to receive it.
 

lib/calculator.ex

@@ -1,27 +1,41 @@
 defmodule Odometex.Calculator do
+  @moduledoc """
+  Provides different distances methods with a range of ordering options.
+  """
+
   alias Odometex.Result
 
   @distances "#{__DIR__}/../config/distances.json"
     |> File.read!
     |> Poison.decode!(as: [%Result{}])
-
-  def distances_with_times(distance, %{ order: :desc } = options) do
+
+  @doc """
+    Returns a list of results taking first the longest references.
+  """
+  def distances_with_times(distance, %{order: :desc} = options) do
     distances_with_times(
       distance,
       fn(x, y) -> x.meters > y.meters end,
       options.limit
     )
   end
 
-  def distances_with_times(distance, %{ order: :asc } = options) do
+  @doc """
+    Returns a list of results taking first the shortest references.
+  """
+  def distances_with_times(distance, %{order: :asc} = options) do
     distances_with_times(
       distance,
       fn(x, y) -> x.meters < y.meters end,
       options.limit
     )
   end
 
-  def distances_with_times(distance, %{ order: :best_match } = options) do
+   @doc """
+    Returns a list of results taking first the distance comparison (times) 
+    that tends to 1.
+  """
+  def distances_with_times(distance, %{order: :best_match} = options) do
     distances_with_times(
       distance,
       fn(x, y) -> abs(x.meters - distance) < abs(y.meters - distance) end,
@@ -40,6 +54,6 @@ defmodule Odometex.Calculator do
   end
 
   defp times_value(item, distance) do
-    distance / item.meters |> Float.round(6)
+    Float.round(distance / item.meters, 6)
   end
 end

lib/odometex.ex

@@ -1,14 +1,21 @@
 defmodule Odometex do
   @moduledoc """
-  Documentation for Odometex.
+  Provides simple comparisons with global references given a distance.
   """
 
   alias Odometex.Calculator
 
   @compare_default_options %{order: :best_match, limit: 5}
 
   @doc """
-  Returns a list of results with the number of times of each one
+  Returns a list of results with the number of times of each one.
+
+  It could take some options:
+    - order:   You can use three different orders:
+      - best_match: Returns the results such distance comparison (times) tends to 1.
+      - asc: Returns the results given the shortest distances that we have as references.
+      - desc: Returns the results given the longest distances that we have as references.
+    - limit: The number of results to retunr. Default 5.
 
   ## Examples
 
@@ -24,6 +31,11 @@ defmodule Odometex do
         times: 0.015385
       }
     ]
+
+    iex> Odometex.compare(20, order: :desc, limit: 1)
+    [
+      %Odometex.Result{label: "Great Wall", meters: 8851000, times: 2.0e-6}
+    ]
   """
   def compare(distance, options \\ []) do
     merged_options = Enum.into(options, @compare_default_options)

mix.exs

@@ -7,7 +7,11 @@ defmodule Odometex.Mixfile do
       version: "0.1.0",
       elixir: "~> 1.5",
       start_permanent: Mix.env == :prod,
-      deps: deps()
+      deps: deps(),
+      description: description(),
+      name: "Odometex",
+      package: package(),
+      source_url: "https://github.com/dsantosmerino/odometex"
     ]
   end
 
@@ -21,7 +25,21 @@ defmodule Odometex.Mixfile do
   # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
-      {:poison, "~> 3.1"}
+      {:credo, "~> 0.9.1", only: [:dev, :test], runtime: false},
+      {:ex_doc, "~> 0.14", only: :dev},
+      {:poison, "~> 3.1"},
+    ]
+  end
+
+  defp description do
+    "Simple distance comparisons for Elixir."
+  end
+
+  defp package do
+    [
+      maintainers: ["David Santos Merino"],
+      licenses: ["MIT"],
+      links: %{"GitHub" => "https://github.com/dsantosmerino/odometex"}
     ]
   end
 end

mix.lock

@@ -1 +1,7 @@
-%{"poison": {:hex, :poison, "3.1.0", "d9eb636610e096f86f25d9a46f35a9facac35609a7591b3be3326e99a0484665", [], [], "hexpm"}}
+%{
+  "bunt": {:hex, :bunt, "0.2.0", "951c6e801e8b1d2cbe58ebbd3e616a869061ddadcc4863d0a2182541acae9a38", [:mix], [], "hexpm"},
+  "credo": {:hex, :credo, "0.9.2", "841d316612f568beb22ba310d816353dddf31c2d94aa488ae5a27bb53760d0bf", [:mix], [{:bunt, "~> 0.2.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:poison, ">= 0.0.0", [hex: :poison, repo: "hexpm", optional: false]}], "hexpm"},
+  "earmark": {:hex, :earmark, "1.2.5", "4d21980d5d2862a2e13ec3c49ad9ad783ffc7ca5769cf6ff891a4553fbaae761", [:mix], [], "hexpm"},
+  "ex_doc": {:hex, :ex_doc, "0.18.3", "f4b0e4a2ec6f333dccf761838a4b253d75e11f714b85ae271c9ae361367897b7", [:mix], [{:earmark, "~> 1.1", [hex: :earmark, repo: "hexpm", optional: false]}], "hexpm"},
+  "poison": {:hex, :poison, "3.1.0", "d9eb636610e096f86f25d9a46f35a9facac35609a7591b3be3326e99a0484665", [], [], "hexpm"},
+}