✌️ better documentation, thanks inch!

.circleci/config.yml

@@ -22,6 +22,9 @@ jobs:
       - run: mix deps.get
 
       - run: mix credo
+
+      - run: MIX_ENV=docs mix inch.report
+
       - run: MIX_ENV=test mix coveralls.json
       - run: MIX_ENV=test bash <(curl -s https://codecov.io/bash)
 

.gitignore

@@ -24,3 +24,4 @@ lib_lat_lon-*.tar
 
 /.elixir_ls/
 
+/docs/

README.md

@@ -1,11 +1,13 @@
-# ![{:ok, 📍}](/stuff/images/logo.png?raw=true) LibLatLon
+# ![{:ok, 📍}](/stuff/images/logo.png?raw=true)
 
-[![CircleCI](https://circleci.com/gh/amotion-city/lib_lat_lon.svg?style=svg)](https://circleci.com/gh/amotion-city/lib_lat_lon) 
 [![HexPM](https://img.shields.io/hexpm/v/lib_lat_lon.svg)](https://hex.pm/packages/lib_lat_lon) 
+[![CircleCI](https://circleci.com/gh/amotion-city/lib_lat_lon.svg?style=svg)](https://circleci.com/gh/amotion-city/lib_lat_lon) 
+[![Inline docs](http://inch-ci.org/github/amotion-city/lib_lat_lon.svg)](http://inch-ci.org/github/amotion-city/lib_lat_lon) 
 [![License badge](https://img.shields.io/hexpm/l/lib_lat_lon.svg)](https://github.com/amotion-city/lib_lat_lon/blob/master/LICENSE.md) 
 [![Read the Docs](/stuff/images/docs-passing.png?raw=true)](https://hexdocs.pm/lib_lat_lon) 
-[![Code coverage badge](https://img.shields.io/codecov/c/github/amotion-city/lib_lat_lon/master.svg)](https://codecov.io/gh/amotion-city/lib_lat_lon/branch/master) 
-handy library for managing geo coordinates, that includes _direct/reverse geocoding_ features
+[![Code coverage badge](https://img.shields.io/codecov/c/github/amotion-city/lib_lat_lon/master.svg)]
+
+**`LibLatLon`** is a **handy library** for managing **geo coordinates**, that includes **_direct/reverse geocoding_** features
 
 ## Installation
 

lib/lib_lat_lon.ex

@@ -37,6 +37,7 @@ defmodule LibLatLon do
       }
 
   """
+  @spec lookup(any(), atom(), %{}) :: {:ok, LibLatLon.Info.t()} | {:error, any()}
   def lookup(value, provider \\ @default_provider, opts \\ %{}) do
     case guess_lookup(provider, value, opts) do
       {:ok, result} -> result

lib/lib_lat_lon/data/coords.ex

@@ -105,7 +105,7 @@ defmodule LibLatLon.Coords do
               {}
               | number()
             )
-        ) :: LibLatLon.Coords.t() | number() | nil
+        ) :: LibLatLon.Coords.t() | number() | nil | {:error, any()}
 
   def borrow(nil), do: nil
   def borrow([nil, _]), do: nil
@@ -249,7 +249,7 @@ defmodule LibLatLon.Coords do
   def lend(%Coords{lat: dms1, lon: dms2}), do: lend(dms1, dms2)
 
   @spec do_lend({number(), 0 | 1}) :: dms_ss()
-  def do_lend({dms, idx}) when is_number(dms) do
+  defp do_lend({dms, idx}) when is_number(dms) do
     ss = dms > 0
     abs = if ss, do: dms, else: -dms
     d = abs |> Float.floor() |> Kernel.round()
@@ -277,7 +277,7 @@ defmodule LibLatLon.Coords do
       iex> LibLatLon.Coords.coordinate("test/inputs/unknown.jpg")
       {:error, {:weird_input, [nil]}}
   """
-  @spec coordinate(nil | binary() | %{} | any()) :: {:ok, LibLatLon.Coords.t()} | {:error, atom()}
+  @spec coordinate(nil | binary() | %{} | any()) :: {:ok, LibLatLon.Coords.t()} | {:error, any()}
   def coordinate(<<@image_start_marker::16, _::binary>> = buffer),
     do: with({:ok, info} <- Exexif.exif_from_jpeg_buffer(buffer), do: coordinate(info))
 
@@ -299,7 +299,13 @@ defmodule LibLatLon.Coords do
 
   def coordinate(%{gps: %Exexif.Data.Gps{} = gps}), do: coordinate(gps)
 
-  def coordinate(whatever), do: {:ok, Coords.borrow(whatever)}
+  def coordinate(whatever) do
+    case Coords.borrow(whatever) do
+      {:error, reason} -> {:error, reason}
+      %LibLatLon.Coords{} = coords -> {:ok, coords}
+      whatever -> {:error, {:malformed, whatever}}
+    end
+  end
 
   @doc """
   Same as `LibLatLon.Coords.coordinate/1`, but banged.
@@ -309,7 +315,7 @@ defmodule LibLatLon.Coords do
       iex> LibLatLon.Coords.coordinate!("test/inputs/1.jpg")
       #Coord<[lat: 41.37600333333334, lon: 2.1486783333333332, fancy: "41°22´33.612˝N,2°8´55.242˝E"]>
   """
-  @spec coordinate!(nil | binary() | %{} | any()) :: LibLatLon.Coords.t()
+  @spec coordinate!(nil | binary() | %{} | any()) :: LibLatLon.Coords.t() | no_return()
   def coordinate!(whatever) do
     case coordinate(whatever) do
       {:ok, result} -> result
@@ -320,6 +326,7 @@ defmodule LibLatLon.Coords do
   ##############################################################################
 
   defimpl String.Chars, for: LibLatLon.Coords do
+    @doc "Returns a fancy representation of coordinates, like “41°22´33.612˝N,2°8´55.242˝E”"
     def to_string(term) do
       # {{{41, 23, 16.0}, "N"}, {{2, 11, 50.0}, "E"}}
       {{{d1, m1, s1}, ss1}, {{d2, m2, s2}, ss2}} = LibLatLon.Coords.lend(term)
@@ -330,6 +337,10 @@ defmodule LibLatLon.Coords do
   defimpl Inspect, for: LibLatLon.Coords do
     import Inspect.Algebra
 
+    @doc ~S"""
+    Returns a `doc`, containing the latitude, the longiture,
+      and the fancy representation of coordinates, like “41°22´33.612˝N,2°8´55.242˝E”
+    """
     def inspect(%{lat: lat, lon: lon}, opts) do
       inner = [lat: lat, lon: lon, fancy: to_string(%LibLatLon.Coords{lat: lat, lon: lon})]
       concat(["#Coord<", to_doc(inner, opts), ">"])

lib/lib_lat_lon/data/info.ex

@@ -77,6 +77,7 @@ defmodule LibLatLon.Info do
     fields in unified format.
   """
 
+  @spec from_map(map() | list()) :: {:ok, LibLatLon.Info.t} | {:error, atom()}
   def from_map(%{} = map) do
     with {:ok, bounds} <- LibLatLon.Bounds.from_lat_lon(map.bounds),
          {:ok, coords} <- LibLatLon.Coords.coordinate({map.lat, map.lon}) do
@@ -97,6 +98,7 @@ defmodule LibLatLon.Info do
   @doc """
   The same as `LibLatLon.Info.from_map/1`, but banged.
   """
+  @spec from_map!(map() | list()) :: LibLatLon.Info.t | no_return()
   def from_map!(%{} = input), do: with({:ok, result} <- from_map(input), do: result)
   def from_map!([]), do: raise LibLatLon.Issue, reason: :no_data
   def from_map!([%{} = input]), do: from_map!(input)
@@ -115,6 +117,7 @@ defmodule LibLatLon.Info do
       iex> LibLatLon.Info.format(info, "⚑ %{country}, %{city}, %{postcode}.")
       "⚑ España, Barcelona, 08021."
   """
+  @spec format(LibLatLon.Info.t, binary()) :: binary()
   def format(%LibLatLon.Info{details: %{} = content}, format) when is_binary(format) do
     ~r|%{(.*?)}|
     |> Regex.replace(format, fn _, term ->

mix.exs

@@ -3,7 +3,7 @@ defmodule LibLatLon.MixProject do
 
   @app :lib_lat_lon
   @app_name "LibLatLon"
-  @version "0.3.5"
+  @version "0.4.0"
 
   def project do
     [
@@ -43,7 +43,8 @@ defmodule LibLatLon.MixProject do
       {:exexif, "~> 0.0"},
       {:porcelain, "~> 2.0"},
       {:credo, "~> 0.8", only: [:dev, :test]},
-      {:ex_doc, ">= 0.0.0", only: :dev},
+      {:inch_ex, ">= 0.0.0", only: [:dev, :docs]},
+      {:ex_doc, ">= 0.0.0", only: [:dev, :docs]},
       {:excoveralls, "~> 0.8", only: :test}
       # {:dep_from_git, git: "https://github.com/elixir-lang/my_dep.git", tag: "0.1.0"},
     ]

mix.lock

@@ -10,10 +10,12 @@
   "hackney": {:hex, :hackney, "1.10.1", "c38d0ca52ea80254936a32c45bb7eb414e7a96a521b4ce76d00a69753b157f21", [:rebar3], [{:certifi, "2.0.0", [hex: :certifi, optional: false]}, {:idna, "5.1.0", [hex: :idna, optional: false]}, {:metrics, "1.0.1", [hex: :metrics, optional: false]}, {:mimerl, "1.0.2", [hex: :mimerl, optional: false]}, {:ssl_verify_fun, "1.1.1", [hex: :ssl_verify_fun, optional: false]}]},
   "httpoison": {:hex, :httpoison, "1.0.0", "1f02f827148d945d40b24f0b0a89afe40bfe037171a6cf70f2486976d86921cd", [:mix], [{:hackney, "~> 1.8", [hex: :hackney, optional: false]}]},
   "idna": {:hex, :idna, "5.1.0", "d72b4effeb324ad5da3cab1767cb16b17939004e789d8c0ad5b70f3cea20c89a", [:rebar3], [{:unicode_util_compat, "0.3.1", [hex: :unicode_util_compat, optional: false]}]},
+  "inch_ex": {:hex, :inch_ex, "0.5.6", "418357418a553baa6d04eccd1b44171936817db61f4c0840112b420b8e378e67", [:mix], [{:poison, "~> 1.5 or ~> 2.0 or ~> 3.0", [hex: :poison, optional: false]}]},
   "jason": {:hex, :jason, "1.0.0-rc.2", "149715b008fa2a8a5d663fcbe09176e037df402e0346b48eb19f56b59f298dca", [:mix], [{:decimal, "~> 1.0", [hex: :decimal, optional: true]}]},
   "jsx": {:hex, :jsx, "2.8.3", "a05252d381885240744d955fbe3cf810504eb2567164824e19303ea59eef62cf", [:mix, :rebar3], []},
   "metrics": {:hex, :metrics, "1.0.1", "25f094dea2cda98213cecc3aeff09e940299d950904393b2a29d191c346a8486", [:rebar3], []},
   "mimerl": {:hex, :mimerl, "1.0.2", "993f9b0e084083405ed8252b99460c4f0563e41729ab42d9074fd5e52439be88", [:rebar3], []},
+  "poison": {:hex, :poison, "3.1.0", "d9eb636610e096f86f25d9a46f35a9facac35609a7591b3be3326e99a0484665", [:mix], []},
   "porcelain": {:hex, :porcelain, "2.0.3", "2d77b17d1f21fed875b8c5ecba72a01533db2013bd2e5e62c6d286c029150fdc", [:mix], []},
   "ssl_verify_fun": {:hex, :ssl_verify_fun, "1.1.1", "28a4d65b7f59893bc2c7de786dec1e1555bd742d336043fe644ae956c3497fbe", [:make, :rebar], []},
   "unicode_util_compat": {:hex, :unicode_util_compat, "0.3.1", "a1f612a7b512638634a603c8f401892afbf99b8ce93a45041f8aaca99cadb85e", [:rebar3], []},