Some typespecs and docs

apps/transport/lib/registry/engine.ex

@@ -13,7 +13,12 @@ defmodule Transport.Registry.Engine do
 
   require Logger
 
-  @spec execute(output_file :: Path.t(), list()) :: :ok
+  @type option :: {:limit, integer()} | {:formats, [String.t()]}
+
+  @doc """
+  execute("/tmp/registre-arrets.csv", formats: ~w(GTFS NeTEx), limit: 100)
+  """
+  @spec execute(output_file :: Path.t(), opts :: [option]) :: :ok
   def execute(output_file, opts \\ []) do
     limit = Keyword.get(opts, :limit, 1_000_000)
     formats = Keyword.get(opts, :formats, ~w(GTFS NeTEx))

apps/transport/lib/registry/result.ex

@@ -2,19 +2,28 @@ defmodule Transport.Registry.Result do
   @moduledoc """
   Type and utilities to represent results.
   """
+  require Integer
 
   @type t(positive) :: {:ok, positive} | {:error, binary()}
 
   def ok(positive), do: {:ok, positive}
 
   def error(message), do: {:error, message}
 
+  @doc """
+  iex> [{:ok, "valid"}, {:error, "invalid"}, {:ok, "relevant"}] |> cat_results()
+  ["valid", "relevant"]
+  """
   @spec cat_results(Stream.t(t(term()))) :: Stream.t(term())
   def cat_results(enumerable), do: Stream.flat_map(enumerable, &keep_ok/1)
 
   defp keep_ok({:ok, result}), do: [result]
   defp keep_ok(_), do: []
 
+  @doc """
+  iex> 1..10 |> map_result(fn v -> if Integer.is_odd(v) do {:ok, v} else {:error, "Even Steven"} end end)
+  [1, 3, 5, 7, 9]
+  """
   @spec map_result(Stream.t(term()), (term() -> t(term()))) :: Stream.t(term())
   def map_result(enumerable, mapper) do
     enumerable

apps/transport/test/registry/result_test.exs

@@ -3,6 +3,7 @@ defmodule Transport.Registry.ResultTest do
 
   require Integer
   alias Transport.Registry.Result
+  doctest Result
 
   test "cat_results" do
     assert [] == cat_results([])